@xcelsior/ui-spreadsheets 1.0.1

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@xcelsior/ui-spreadsheets",
+  "version": "1.0.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "tailwind-merge": "^2.2.2",
+    "clsx": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/addon-links": "^8.6.14",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "@storybook/testing-library": "^0.2.2",
+    "storybook": "^8.6.14",
+    "react-icons": "^4.12.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "tailwindcss": "^4.0.0",
+    "@xcelsior/design-system": "1.0.6"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-hook-form": "^7",
+    "@xcelsior/design-system": "^1.0.6",
+    "flowbite": "^1.5.3",
+    "flowbite-react": "^0.12"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup && tsc --noEmit",
+    "prepublish": "npm run build",
+    "build:watch": "tsup --watch",
+    "dev": "tsup --watch",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build",
+    "lint": "biome check . && tsc",
+    "type-check": "tsc --noEmit"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    plugins: {
+        '@tailwindcss/postcss': {},
+    },
+};

package/src/components/ColorPickerPopover.tsx

@@ -0,0 +1,73 @@
+import { cn } from '../utils';
+import { HIGHLIGHT_COLORS } from '../hooks/useSpreadsheetHighlighting';
+
+export type ColorPaletteType = 'row' | 'column';
+
+export interface ColorPickerPopoverProps {
+    /** Title displayed in the popover */
+    title: string;
+    /** Type of color palette to use */
+    paletteType?: ColorPaletteType;
+    /** Custom colors array (overrides paletteType) */
+    colors?: (string | null)[];
+    /** Callback when a color is selected */
+    onSelectColor: (color: string | null) => void;
+    /** Callback when the popover is closed/cancelled */
+    onClose: () => void;
+    /** Additional className for the container */
+    className?: string;
+}
+
+/**
+ * A reusable color picker popover component for highlighting.
+ * Supports both row (darker) and column (lighter) color palettes.
+ */
+export function ColorPickerPopover({
+    title,
+    paletteType = 'column',
+    colors,
+    onSelectColor,
+    onClose,
+    className,
+}: ColorPickerPopoverProps) {
+    // Use custom colors if provided, otherwise use palette based on type
+    const colorPalette = colors ?? [...HIGHLIGHT_COLORS[paletteType], null];
+
+    return (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+            <div className={cn('bg-white rounded-lg shadow-xl p-4 w-64', className)}>
+                <h3 className="text-sm font-semibold mb-3">{title}</h3>
+                <div className="grid grid-cols-5 gap-2">
+                    {colorPalette.map((color) => (
+                        <button
+                            key={color || 'clear'}
+                            type="button"
+                            onClick={() => onSelectColor(color)}
+                            className={cn(
+                                'w-8 h-8 rounded border-2 transition-transform hover:scale-110',
+                                color
+                                    ? 'border-gray-300'
+                                    : 'border-gray-300 bg-white flex items-center justify-center text-gray-400 text-xs'
+                            )}
+                            style={color ? { backgroundColor: color } : undefined}
+                            title={color || 'Clear highlight'}
+                        >
+                            {!color && '✕'}
+                        </button>
+                    ))}
+                </div>
+                <div className="flex justify-end mt-4">
+                    <button
+                        type="button"
+                        onClick={onClose}
+                        className="px-3 py-1.5 text-sm text-gray-600 hover:bg-gray-100 rounded transition-colors"
+                    >
+                        Cancel
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}
+
+ColorPickerPopover.displayName = 'ColorPickerPopover';

package/src/components/ColumnHeaderActions.tsx

@@ -0,0 +1,139 @@
+import type React from 'react';
+import { HiColorSwatch, HiFilter } from 'react-icons/hi';
+import { MdOutlinePushPin, MdPushPin } from 'react-icons/md';
+import { cn } from '../utils';
+
+export interface ColumnHeaderActionsProps {
+    /** Whether filtering is enabled for this column */
+    enableFiltering?: boolean;
+    /** Whether highlighting is enabled for this column */
+    enableHighlighting?: boolean;
+    /** Whether pinning is enabled for this column */
+    enablePinning?: boolean;
+    /** Whether the column currently has an active filter */
+    hasActiveFilter?: boolean;
+    /** Whether the column currently has an active highlight */
+    hasActiveHighlight?: boolean;
+    /** Whether the column is currently pinned */
+    isPinned?: boolean;
+    /** Callback when filter button is clicked */
+    onFilterClick?: () => void;
+    /** Callback when highlight button is clicked */
+    onHighlightClick?: () => void;
+    /** Callback when pin button is clicked */
+    onPinClick?: () => void;
+    /** Title for the filter button */
+    filterTitle?: string;
+    /** Title for the highlight button */
+    highlightTitle?: string;
+    /** Title for the pin button when pinned */
+    pinnedTitle?: string;
+    /** Title for the pin button when unpinned */
+    unpinnedTitle?: string;
+    /** Additional className */
+    className?: string;
+}
+
+/**
+ * Reusable action buttons for column headers (filter, highlight, pin).
+ * Works for both regular columns and the row index column.
+ */
+export function ColumnHeaderActions({
+    enableFiltering = false,
+    enableHighlighting = false,
+    enablePinning = true,
+    hasActiveFilter = false,
+    hasActiveHighlight = false,
+    isPinned = false,
+    onFilterClick,
+    onHighlightClick,
+    onPinClick,
+    filterTitle = 'Filter column',
+    highlightTitle = 'Highlight column',
+    pinnedTitle = 'Unpin column',
+    unpinnedTitle = 'Pin column',
+    className,
+}: ColumnHeaderActionsProps) {
+    const handleClick = (e: React.MouseEvent) => {
+        e.stopPropagation();
+    };
+
+    const handleKeyDown = (e: React.KeyboardEvent) => {
+        e.stopPropagation();
+    };
+
+    return (
+        <button
+            type="button"
+            className={cn('flex items-center gap-0.5', className)}
+            onClick={handleClick}
+            onKeyDown={handleKeyDown}
+        >
+            {/* Filter button */}
+            {enableFiltering && onFilterClick && (
+                <button
+                    type="button"
+                    onClick={(e) => {
+                        e.stopPropagation();
+                        onFilterClick();
+                    }}
+                    className={cn(
+                        'p-0.5 hover:bg-gray-200 rounded transition-opacity',
+                        hasActiveFilter
+                            ? 'text-blue-600 opacity-100'
+                            : 'text-gray-400 opacity-0 group-hover:opacity-100'
+                    )}
+                    title={filterTitle}
+                >
+                    <HiFilter className="h-3 w-3" />
+                </button>
+            )}
+
+            {/* Highlight button */}
+            {enableHighlighting && onHighlightClick && (
+                <button
+                    type="button"
+                    onClick={(e) => {
+                        e.stopPropagation();
+                        onHighlightClick();
+                    }}
+                    className={cn(
+                        'p-0.5 hover:bg-gray-200 rounded transition-opacity',
+                        hasActiveHighlight
+                            ? 'text-amber-500 opacity-100'
+                            : 'text-gray-400 opacity-0 group-hover:opacity-100'
+                    )}
+                    title={highlightTitle}
+                >
+                    <HiColorSwatch className="h-3 w-3" />
+                </button>
+            )}
+
+            {/* Pin button */}
+            {enablePinning && onPinClick && (
+                <button
+                    type="button"
+                    onClick={(e) => {
+                        e.stopPropagation();
+                        onPinClick();
+                    }}
+                    className={cn(
+                        'p-0.5 hover:bg-gray-200 rounded transition-opacity',
+                        isPinned
+                            ? 'text-blue-600 opacity-100'
+                            : 'text-gray-400 opacity-0 group-hover:opacity-100'
+                    )}
+                    title={isPinned ? pinnedTitle : unpinnedTitle}
+                >
+                    {isPinned ? (
+                        <MdPushPin className="h-3 w-3" />
+                    ) : (
+                        <MdOutlinePushPin className="h-3 w-3" />
+                    )}
+                </button>
+            )}
+        </button>
+    );
+}
+
+ColumnHeaderActions.displayName = 'ColumnHeaderActions';

package/src/components/CommentModals.tsx

@@ -0,0 +1,137 @@
+import { cn } from '../utils';
+import type { CellComment } from '../types';
+
+// ==================== Add Comment Modal ====================
+
+export interface AddCommentModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Current comment text */
+    commentText: string;
+    /** Callback to update comment text */
+    onCommentTextChange: (text: string) => void;
+    /** Callback to add the comment */
+    onAdd: () => void;
+    /** Callback to close/cancel */
+    onClose: () => void;
+}
+
+export function AddCommentModal({
+    isOpen,
+    commentText,
+    onCommentTextChange,
+    onAdd,
+    onClose,
+}: AddCommentModalProps) {
+    if (!isOpen) return null;
+
+    return (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+            <div className="bg-white rounded-lg shadow-xl p-6 w-96 max-w-full mx-4">
+                <h3 className="text-lg font-semibold mb-4">Add Row Comment</h3>
+                <textarea
+                    value={commentText}
+                    onChange={(e) => onCommentTextChange(e.target.value)}
+                    placeholder="Enter your comment..."
+                    className="w-full h-24 p-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-blue-500 resize-none"
+                />
+                <div className="flex justify-end gap-2 mt-4">
+                    <button
+                        type="button"
+                        onClick={onClose}
+                        className="px-4 py-2 text-gray-600 hover:bg-gray-100 rounded-lg transition-colors"
+                    >
+                        Cancel
+                    </button>
+                    <button
+                        type="button"
+                        onClick={onAdd}
+                        disabled={!commentText.trim()}
+                        className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+                    >
+                        Add Comment
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}
+
+AddCommentModal.displayName = 'AddCommentModal';
+
+// ==================== View Comments Modal ====================
+
+export interface ViewCommentsModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Comments to display */
+    comments: CellComment[];
+    /** Callback to toggle comment resolved status */
+    onToggleResolved: (commentId: string) => void;
+    /** Callback to close the modal */
+    onClose: () => void;
+}
+
+export function ViewCommentsModal({
+    isOpen,
+    comments,
+    onToggleResolved,
+    onClose,
+}: ViewCommentsModalProps) {
+    if (!isOpen) return null;
+
+    return (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+            <div className="bg-white rounded-lg shadow-xl p-6 w-[480px] max-w-full mx-4 max-h-[80vh] flex flex-col">
+                <div className="flex items-center justify-between mb-4">
+                    <h3 className="text-lg font-semibold">Row Comments</h3>
+                    <button
+                        type="button"
+                        onClick={onClose}
+                        className="p-1 hover:bg-gray-100 rounded-lg transition-colors"
+                    >
+                        ✕
+                    </button>
+                </div>
+                <div className="flex-1 overflow-y-auto space-y-3">
+                    {comments.map((comment) => (
+                        <div
+                            key={comment.id}
+                            className={cn(
+                                'p-3 rounded-lg border',
+                                comment.resolved
+                                    ? 'bg-gray-50 border-gray-200'
+                                    : 'bg-yellow-50 border-yellow-200'
+                            )}
+                        >
+                            <div className="flex items-start justify-between gap-2">
+                                <p className="text-sm text-gray-700">{comment.text}</p>
+                                <button
+                                    type="button"
+                                    onClick={() => onToggleResolved(comment.id)}
+                                    className={cn(
+                                        'flex-shrink-0 px-2 py-1 text-xs rounded transition-colors',
+                                        comment.resolved
+                                            ? 'bg-gray-200 text-gray-600 hover:bg-gray-300'
+                                            : 'bg-green-100 text-green-700 hover:bg-green-200'
+                                    )}
+                                >
+                                    {comment.resolved ? 'Reopen' : 'Resolve'}
+                                </button>
+                            </div>
+                            <div className="flex items-center gap-2 mt-2 text-xs text-gray-500">
+                                {comment.author && <span>{comment.author}</span>}
+                                <span>{new Date(comment.timestamp).toLocaleString()}</span>
+                            </div>
+                        </div>
+                    ))}
+                    {comments.length === 0 && (
+                        <p className="text-center text-gray-500 py-8">No comments for this row.</p>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+}
+
+ViewCommentsModal.displayName = 'ViewCommentsModal';

package/src/components/KeyboardShortcutsModal.tsx

@@ -0,0 +1,119 @@
+import React from 'react';
+
+export interface KeyboardShortcutsModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Callback to close the modal */
+    onClose: () => void;
+    /** Shortcut definitions */
+    shortcuts: {
+        general: Array<{ label: string; keys: string[] }>;
+        rowSelection: Array<{ label: string; keys: string[] }>;
+        editing: Array<{ label: string; keys: string[] }>;
+        rowActions: Array<{ label: string; description: string }>;
+    };
+}
+
+/**
+ * Modal component displaying keyboard shortcuts for the spreadsheet.
+ */
+export function KeyboardShortcutsModal({
+    isOpen,
+    onClose,
+    shortcuts,
+}: KeyboardShortcutsModalProps) {
+    if (!isOpen) return null;
+
+    return (
+        <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
+            <div className="bg-white rounded-lg shadow-xl p-6 w-full max-w-2xl max-h-[80vh] overflow-y-auto mx-4">
+                <div className="flex items-center justify-between mb-4">
+                    <h3 className="text-xl font-bold text-gray-900">Keyboard Shortcuts</h3>
+                    <button
+                        type="button"
+                        onClick={onClose}
+                        className="p-1 hover:bg-gray-100 rounded"
+                    >
+                        <span className="text-gray-500 text-xl">✕</span>
+                    </button>
+                </div>
+
+                <div className="space-y-6">
+                    {/* General Section */}
+                    <ShortcutSection title="General">
+                        {shortcuts.general.map((shortcut, index) => (
+                            <ShortcutRow key={index} label={shortcut.label} keys={shortcut.keys} />
+                        ))}
+                    </ShortcutSection>
+
+                    {/* Row Selection Section */}
+                    <ShortcutSection title="Row Selection">
+                        {shortcuts.rowSelection.map((shortcut, index) => (
+                            <ShortcutRow key={index} label={shortcut.label} keys={shortcut.keys} />
+                        ))}
+                    </ShortcutSection>
+
+                    {/* Editing Section */}
+                    <ShortcutSection title="Editing">
+                        {shortcuts.editing.map((shortcut, index) => (
+                            <ShortcutRow key={index} label={shortcut.label} keys={shortcut.keys} />
+                        ))}
+                    </ShortcutSection>
+
+                    {/* Row Actions Section */}
+                    <ShortcutSection title="Row Actions (hover over row #)">
+                        {shortcuts.rowActions.map((action, index) => (
+                            <div key={index} className="flex items-center justify-between">
+                                <span className="text-gray-600 text-sm">{action.label}</span>
+                                <span className="text-gray-500 text-xs">{action.description}</span>
+                            </div>
+                        ))}
+                    </ShortcutSection>
+                </div>
+            </div>
+        </div>
+    );
+}
+
+interface ShortcutSectionProps {
+    title: string;
+    children: React.ReactNode;
+}
+
+function ShortcutSection({ title, children }: ShortcutSectionProps) {
+    return (
+        <div>
+            <h4 className="text-gray-900 font-semibold mb-3">{title}</h4>
+            <div className="space-y-2">{children}</div>
+        </div>
+    );
+}
+
+interface ShortcutRowProps {
+    label: string;
+    keys: string[];
+}
+
+function ShortcutRow({ label, keys }: ShortcutRowProps) {
+    return (
+        <div className="flex items-center justify-between">
+            <span className="text-gray-600 text-sm">{label}</span>
+            <div className="flex items-center gap-1">
+                {keys.map((key, index) => (
+                    <React.Fragment key={index}>
+                        {index > 0 && <span className="text-gray-400">+</span>}
+                        {key.includes('Click') ? (
+                            <span className="text-gray-500 text-xs">{key}</span>
+                        ) : (
+                            <kbd className="px-2 py-1 bg-gray-100 text-gray-800 rounded text-xs border border-gray-200">
+                                {key}
+                            </kbd>
+                        )}
+                    </React.Fragment>
+                ))}
+            </div>
+        </div>
+    );
+}
+
+KeyboardShortcutsModal.displayName = 'KeyboardShortcutsModal';

package/src/components/RowIndexColumnHeader.tsx

@@ -0,0 +1,70 @@
+import { cn } from '../utils';
+import { ColumnHeaderActions } from './ColumnHeaderActions';
+import { ROW_INDEX_COLUMN_WIDTH } from '../hooks/useSpreadsheetPinning';
+
+export interface RowIndexColumnHeaderProps {
+    /** Whether highlighting is enabled */
+    enableHighlighting?: boolean;
+    /** Current highlight color (if any) */
+    highlightColor?: string;
+    /** Whether the column is pinned */
+    isPinned?: boolean;
+    /** Callback when highlight button is clicked */
+    onHighlightClick?: () => void;
+    /** Callback when pin button is clicked */
+    onPinClick?: () => void;
+    /** Whether this is in the column groups row (needs rowSpan=2) */
+    hasColumnGroups?: boolean;
+    /** Additional className */
+    className?: string;
+}
+
+/**
+ * Row index column header (#) with highlight and pin actions.
+ * Uses the same ColumnHeaderActions component as regular columns for consistency.
+ */
+export function RowIndexColumnHeader({
+    enableHighlighting = false,
+    highlightColor,
+    isPinned = false,
+    onHighlightClick,
+    onPinClick,
+    hasColumnGroups = false,
+    className,
+}: RowIndexColumnHeaderProps) {
+    return (
+        <th
+            className={cn(
+                'border border-gray-200 px-2 py-1.5 text-center font-bold text-gray-700 group',
+                isPinned ? 'z-30' : 'z-20',
+                className
+            )}
+            rowSpan={hasColumnGroups ? 2 : undefined}
+            style={{
+                minWidth: `${ROW_INDEX_COLUMN_WIDTH}px`,
+                width: `${ROW_INDEX_COLUMN_WIDTH}px`,
+                position: 'sticky',
+                top: 0,
+                left: isPinned ? 0 : undefined,
+                backgroundColor: highlightColor || 'rgb(243 244 246)',
+            }}
+        >
+            <div className="flex items-center justify-center gap-1">
+                <span>#</span>
+                <ColumnHeaderActions
+                    enableHighlighting={enableHighlighting}
+                    enablePinning={true}
+                    hasActiveHighlight={!!highlightColor}
+                    isPinned={isPinned}
+                    onHighlightClick={onHighlightClick}
+                    onPinClick={onPinClick}
+                    highlightTitle="Highlight row index column"
+                    pinnedTitle="Unpin row index column"
+                    unpinnedTitle="Pin row index column"
+                />
+            </div>
+        </th>
+    );
+}
+
+RowIndexColumnHeader.displayName = 'RowIndexColumnHeader';