react-excel-lite 0.2.0 → 0.4.0

package/README.md

@@ -8,15 +8,22 @@
 
 A lightweight, Excel-like editable grid component for React.
 
+## Demo
+
+[react-excel-lite-demo](https://prkgnt.github.io/react-excel-lite/)
+
 ## Features
 
 - Excel-like cell selection (click & drag)
+- Keyboard navigation (Arrow keys to move, Shift+Arrow to extend selection)
 - Copy/Paste support (Ctrl+C / Ctrl+V)
 - Auto Fill with arithmetic sequence detection (drag fill handle)
-- Grouped column headers with custom styling
-- Row headers with custom styling
-- Keyboard shortcuts (Delete/Backspace to clear)
+- Grouped column headers with rowSpan support
+- Grouped row headers with rowSpan support
+- Click outside to clear selection
+- Double-click or type to edit cells
 - Expandable input field when editing (text overflow handling)
+- Keyboard shortcuts (Delete/Backspace to clear)
 - **Styling-agnostic**: Works with Tailwind CSS, CSS Modules, plain CSS, or any styling solution
 - Zero external dependencies
 
@@ -45,15 +52,16 @@ function App() {
 
 ## Props
 
-| Prop             | Type                         | Required | Description                 |
-| ---------------- | ---------------------------- | -------- | --------------------------- |
-| `data`           | `string[][]`                 | Yes      | 2D array of strings         |
-| `onChange`       | `(data: string[][]) => void` | Yes      | Callback when data changes  |
-| `rowHeaders`     | `HeaderGroup[]`              | No       | Row header definitions      |
-| `colHeaders`     | `HeaderGroup[]`              | No       | Grouped column headers      |
-| `className`      | `string`                     | No       | CSS class for container     |
-| `rowHeaderTitle` | `string`                     | No       | Title for row header column |
-| `styles`         | `GridStyles`                 | No       | Style configuration object  |
+| Prop             | Type                                      | Required | Description                        |
+| ---------------- | ----------------------------------------- | -------- | ---------------------------------- |
+| `data`           | `string[][]`                              | Yes      | 2D array of strings                |
+| `onChange`       | `(data: string[][]) => void`              | Yes      | Callback when data changes         |
+| `rowHeaders`     | `HeaderGroup[]`                           | No       | Grouped row headers                |
+| `colHeaders`     | `HeaderGroup[]`                           | No       | Grouped column headers             |
+| `className`      | `string`                                  | No       | CSS class for container            |
+| `rowHeaderTitle` | `string`                                  | No       | Title for row header column        |
+| `styles`         | `GridStyles`                              | No       | Style configuration object         |
+| `cellStyles`     | `(coord: CellCoord) => string｜undefined` | No       | Function to style individual cells |
 
 ## With Headers
 
@@ -71,16 +79,18 @@ function App() {
   const colHeaders: HeaderGroup[] = [
     {
       label: "Q1",
+      description: "First quarter",
       headers: [
-        { key: "jan", label: "Jan" },
-        { key: "feb", label: "Feb" },
+        { key: "jan", label: "Jan", description: "January" },
+        { key: "feb", label: "Feb", description: "February" },
       ],
     },
     {
       label: "Q2",
+      description: "Second quarter",
       headers: [
-        { key: "mar", label: "Mar" },
-        { key: "apr", label: "Apr" },
+        { key: "mar", label: "Mar", description: "March" },
+        { key: "apr", label: "Apr", description: "April" },
       ],
     },
   ];
@@ -88,6 +98,7 @@ function App() {
   const rowHeaders: HeaderGroup[] = [
     {
       label: "Products",
+      description: "Product categories",
       headers: [
         { key: "prodA", label: "Product A", description: "Main product line" },
         { key: "prodB", label: "Product B", description: "Secondary product" },
@@ -101,12 +112,53 @@ function App() {
       onChange={setData}
       colHeaders={colHeaders}
       rowHeaders={rowHeaders}
-      rowHeaderTitle="Product"
+      rowHeaderTitle="Category"
     />
   );
 }
 ```
 
+## Simple Headers (Without Group Labels)
+
+When all HeaderGroups have no `label`, the grid displays a single header row/column instead of two levels:
+
+```tsx
+const colHeaders: HeaderGroup[] = [
+  {
+    // No label - single header row
+    headers: [
+      { key: "jan", label: "Jan" },
+      { key: "feb", label: "Feb" },
+    ],
+  },
+  {
+    headers: [
+      { key: "mar", label: "Mar" },
+      { key: "apr", label: "Apr" },
+    ],
+  },
+];
+
+const rowHeaders: HeaderGroup[] = [
+  {
+    // No label - single header column
+    headers: [
+      { key: "row1", label: "Row 1" },
+      { key: "row2", label: "Row 2" },
+    ],
+  },
+];
+
+<ExcelGrid
+  data={data}
+  onChange={setData}
+  colHeaders={colHeaders}
+  rowHeaders={rowHeaders}
+/>;
+```
+
+If at least one group has a `label`, the grid shows the two-level layout (group labels + individual headers).
+
 ## Styling
 
 The component comes with sensible default styles built-in. You can customize styles using the `styles` prop with CSS class strings from any styling solution.
@@ -218,14 +270,77 @@ Style individual row headers:
 const rowHeaders: HeaderGroup[] = [
   {
     label: "Regions",
+    className: "bg-slate-700 text-white",
     headers: [
-      { key: "regionA", label: "Region A", className: "bg-slate-700 text-white" },
-      { key: "regionB", label: "Region B", className: "bg-slate-600 text-white" },
+      {
+        key: "regionA",
+        label: "Region A",
+        className: "bg-slate-600 text-white",
+      },
+      {
+        key: "regionB",
+        label: "Region B",
+        className: "bg-slate-500 text-white",
+      },
     ],
   },
 ];
 ```
 
+### Styling Individual Cells
+
+Use the `cellStyles` prop to apply styles to specific cells based on their coordinates:
+
+```tsx
+import { useCallback } from "react";
+import type { CellCoord } from "react-excel-lite";
+
+function App() {
+  const [data, setData] = useState([
+    ["100", "200", "300"],
+    ["400", "500", "600"],
+    ["700", "800", "900"],
+  ]);
+
+  // Memoize to prevent unnecessary re-renders
+  const cellStyles = useCallback((coord: CellCoord) => {
+    // Highlight first row
+    if (coord.row === 0) return "bg-yellow-100";
+    // Highlight specific cell
+    if (coord.row === 1 && coord.col === 1) return "bg-red-100 font-bold";
+    // Highlight cells with negative values (check data)
+    return undefined;
+  }, []);
+
+  return <ExcelGrid data={data} onChange={setData} cellStyles={cellStyles} />;
+}
+```
+
+Common use cases:
+
+- Highlight header rows or columns
+- Show validation errors (e.g., red background for invalid cells)
+- Conditional formatting based on cell values
+- Alternating row colors
+
+```tsx
+// Alternating row colors
+const cellStyles = useCallback((coord: CellCoord) => {
+  return coord.row % 2 === 0 ? "bg-gray-50" : "bg-white";
+}, []);
+
+// Value-based styling (check data in callback)
+const cellStyles = useCallback(
+  (coord: CellCoord) => {
+    const value = Number(data[coord.row]?.[coord.col]);
+    if (value < 0) return "bg-red-100 text-red-700";
+    if (value > 1000) return "bg-green-100 text-green-700";
+    return undefined;
+  },
+  [data],
+);
+```
+
 ## Auto Fill (Arithmetic Sequence)
 
 Select cells with a numeric pattern and drag the fill handle to auto-fill:
@@ -237,11 +352,16 @@ Select cells with a numeric pattern and drag the fill handle to auto-fill:
 
 ## Keyboard Shortcuts
 
-| Shortcut               | Action               |
-| ---------------------- | -------------------- |
-| `Ctrl+C` / `Cmd+C`     | Copy selected cells  |
-| `Ctrl+V` / `Cmd+V`     | Paste from clipboard |
-| `Delete` / `Backspace` | Clear selected cells |
+| Shortcut               | Action                            |
+| ---------------------- | --------------------------------- |
+| `Arrow Keys`           | Move selection                    |
+| `Shift + Arrow Keys`   | Extend selection range            |
+| `Enter`                | Enter edit mode (select all text) |
+| `Any character`        | Enter edit mode and start typing  |
+| `Escape`               | Exit edit mode                    |
+| `Ctrl+C` / `Cmd+C`     | Copy selected cells               |
+| `Ctrl+V` / `Cmd+V`     | Paste from clipboard              |
+| `Delete` / `Backspace` | Clear selected cells              |
 
 ## Exports
 
@@ -253,7 +373,7 @@ Select cells with a numeric pattern and drag the fill handle to auto-fill:
 ### Hooks
 
 - `useGridSelection` - Cell selection logic
-- `useGridClipboard` - Copy/paste logic
+- `useGridClipboard` - Copy/paste and keyboard navigation logic
 - `useGridDragFill` - Fill handle logic
 
 ### Utilities
@@ -289,7 +409,7 @@ interface Header {
 }
 
 interface HeaderGroup {
-  label: string;
+  label?: string;
   headers: Header[];
   description?: string;
   className?: string;
@@ -313,6 +433,7 @@ interface ExcelGridProps {
   className?: string;
   rowHeaderTitle?: string;
   styles?: GridStyles;
+  cellStyles?: (coord: CellCoord) => string | undefined;
 }
 ```
 

package/dist/components/excel-grid.d.ts

@@ -1,3 +1,3 @@
 import { ExcelGridProps } from '../types';
-export declare function ExcelGrid({ data, onChange, rowHeaders, colHeaders, className, rowHeaderTitle, styles, }: ExcelGridProps): import("react/jsx-runtime").JSX.Element;
+export declare function ExcelGrid({ data, onChange, rowHeaders, colHeaders, className, rowHeaderTitle, styles, cellStyles, }: ExcelGridProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=excel-grid.d.ts.map

package/dist/components/excel-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"excel-grid.d.ts","sourceRoot":"","sources":["../../src/components/excel-grid.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,UAAU,CAAC;AAsE1D,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,cAAmB,EACnB,MAAM,GACP,EAAE,cAAc,2CAoShB"}
+{"version":3,"file":"excel-grid.d.ts","sourceRoot":"","sources":["../../src/components/excel-grid.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,UAAU,CAAC;AAsE1D,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,cAAmB,EACnB,MAAM,EACN,UAAU,GACX,EAAE,cAAc,2CAmThB"}

package/dist/components/grid-cell.d.ts

@@ -1,3 +1,3 @@
 import { GridCellProps } from '../types';
-export declare function GridCell({ coord, value, isSelected, isFillTarget, showFillHandle, onMouseDown, onMouseEnter, onChange, onFillHandleMouseDown, styles, }: GridCellProps): import("react/jsx-runtime").JSX.Element;
+export declare function GridCell({ coord, value, isSelected, isFillTarget, showFillHandle, onMouseDown, onMouseEnter, onChange, onFillHandleMouseDown, styles, cellClassName, }: GridCellProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=grid-cell.d.ts.map

package/dist/components/grid-cell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grid-cell.d.ts","sourceRoot":"","sources":["../../src/components/grid-cell.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA8E9C,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,UAAU,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,MAAM,GACP,EAAE,aAAa,2CA4Kf"}
+{"version":3,"file":"grid-cell.d.ts","sourceRoot":"","sources":["../../src/components/grid-cell.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA8E9C,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,UAAU,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,MAAM,EACN,aAAa,GACd,EAAE,aAAa,2CA6Kf"}