gp-grid-vue 0.1.6 → 0.2.3

package/README.md

@@ -0,0 +1,598 @@
+# gp-grid-vue 🏁 🏎️
+
+A high-performance, feature lean Vue 3 data grid component built to manage grids with huge amount (millions) of rows. It's based on its core dependency: `gp-grid-core`, featuring virtual scrolling, cell selection, sorting, filtering, editing, and Excel-like fill handle.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Styling](#styling)
+- [Donations](#donations)
+
+## Features
+
+- **Virtual Scrolling**: Efficiently handles 150,000+ rows through slot-based recycling
+- **Cell Selection**: Single cell, range selection, Shift+click extend, Ctrl+click toggle
+- **Multi-Column Sorting**: Click to sort, Shift+click for multi-column sort
+- **Column Filtering**: Built-in filter row with debounced input
+- **Cell Editing**: Double-click or press Enter to edit, with custom editor support
+- **Fill Handle**: Excel-like drag-to-fill for editable cells
+- **Keyboard Navigation**: Arrow keys, Tab, Enter, Escape, Ctrl+A, Ctrl+C
+- **Custom Renderers**: Registry-based cell, edit, and header renderers
+- **Dark Mode**: Built-in dark theme support
+- **TypeScript**: Full type safety with exported types
+
+## Installation
+
+Use `npm`, `yarn` or `pnpm`
+
+```bash
+pnpm add gp-grid-vue
+```
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { GpGrid, type ColumnDefinition } from "gp-grid-vue";
+
+interface Person {
+  id: number;
+  name: string;
+  age: number;
+  email: string;
+}
+
+const columns: ColumnDefinition[] = [
+  { field: "id", cellDataType: "number", width: 80, headerName: "ID" },
+  { field: "name", cellDataType: "text", width: 150, headerName: "Name" },
+  { field: "age", cellDataType: "number", width: 80, headerName: "Age" },
+  { field: "email", cellDataType: "text", width: 250, headerName: "Email" },
+];
+
+const data: Person[] = [
+  { id: 1, name: "Alice", age: 30, email: "alice@example.com" },
+  { id: 2, name: "Bob", age: 25, email: "bob@example.com" },
+  { id: 3, name: "Charlie", age: 35, email: "charlie@example.com" },
+];
+</script>
+
+<template>
+  <div style="width: 800px; height: 400px">
+    <GpGrid :columns="columns" :row-data="data" :row-height="36" />
+  </div>
+</template>
+```
+
+## Examples
+
+### Client-Side Data Source with Sorting and Filtering
+
+For larger datasets with client-side sort/filter operations:
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import {
+  GpGrid,
+  createClientDataSource,
+  type ColumnDefinition,
+} from "gp-grid-vue";
+
+interface Product {
+  id: number;
+  name: string;
+  price: number;
+  category: string;
+}
+
+const columns: ColumnDefinition[] = [
+  { field: "id", cellDataType: "number", width: 80, headerName: "ID" },
+  { field: "name", cellDataType: "text", width: 200, headerName: "Product" },
+  { field: "price", cellDataType: "number", width: 100, headerName: "Price" },
+  {
+    field: "category",
+    cellDataType: "text",
+    width: 150,
+    headerName: "Category",
+  },
+];
+
+const products = computed<Product[]>(() =>
+  Array.from({ length: 10000 }, (_, i) => ({
+    id: i + 1,
+    name: `Product ${i + 1}`,
+    price: Math.round(Math.random() * 1000) / 10,
+    category: ["Electronics", "Clothing", "Food", "Books"][i % 4],
+  })),
+);
+
+const dataSource = computed(() => createClientDataSource(products.value));
+</script>
+
+<template>
+  <div style="width: 100%; height: 500px">
+    <GpGrid
+      :columns="columns"
+      :data-source="dataSource"
+      :row-height="36"
+      :header-height="40"
+    />
+  </div>
+</template>
+```
+
+### Server-Side Data Source
+
+For datasets too large to load entirely in memory, use a server-side data source:
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import {
+  GpGrid,
+  createServerDataSource,
+  type ColumnDefinition,
+  type DataSourceRequest,
+  type DataSourceResponse,
+} from "gp-grid-vue";
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+  createdAt: string;
+}
+
+const columns: ColumnDefinition[] = [
+  { field: "id", cellDataType: "number", width: 80, headerName: "ID" },
+  { field: "name", cellDataType: "text", width: 150, headerName: "Name" },
+  { field: "email", cellDataType: "text", width: 250, headerName: "Email" },
+  { field: "role", cellDataType: "text", width: 120, headerName: "Role" },
+  {
+    field: "createdAt",
+    cellDataType: "dateString",
+    width: 150,
+    headerName: "Created",
+  },
+];
+
+// API fetch function that handles pagination, sorting, and filtering
+async function fetchUsers(
+  request: DataSourceRequest,
+): Promise<DataSourceResponse<User>> {
+  const { pagination, sort, filter } = request;
+
+  // Build query parameters
+  const params = new URLSearchParams({
+    page: String(pagination.pageIndex),
+    limit: String(pagination.pageSize),
+  });
+
+  // Add sorting parameters
+  if (sort && sort.length > 0) {
+    // Format: sortBy=name:asc,email:desc
+    const sortString = sort.map((s) => `${s.colId}:${s.direction}`).join(",");
+    params.set("sortBy", sortString);
+  }
+
+  // Add filter parameters
+  if (filter) {
+    Object.entries(filter).forEach(([field, value]) => {
+      if (value) {
+        params.set(`filter[${field}]`, String(value));
+      }
+    });
+  }
+
+  // Make API request
+  const response = await fetch(`https://api.example.com/users?${params}`);
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  // Return in DataSourceResponse format
+  return {
+    rows: data.users, // Array of User objects
+    totalRows: data.total, // Total count for virtual scrolling
+  };
+}
+
+// Create server data source - computed to prevent recreation
+const dataSource = computed(() => createServerDataSource<User>(fetchUsers));
+</script>
+
+<template>
+  <div style="width: 100%; height: 600px">
+    <GpGrid
+      :columns="columns"
+      :data-source="dataSource"
+      :row-height="36"
+      :header-height="40"
+      :dark-mode="true"
+    />
+  </div>
+</template>
+```
+
+### Custom Cell Renderers
+
+Use the registry pattern to define reusable renderers:
+
+```vue
+<script setup lang="ts">
+import { h } from "vue";
+import {
+  GpGrid,
+  type ColumnDefinition,
+  type CellRendererParams,
+  type VueCellRenderer,
+} from "gp-grid-vue";
+
+interface Order {
+  id: number;
+  customer: string;
+  total: number;
+  status: "pending" | "shipped" | "delivered" | "cancelled";
+}
+
+// Define reusable renderers
+const cellRenderers: Record<string, VueCellRenderer> = {
+  // Currency formatter
+  currency: (params: CellRendererParams) => {
+    const value = params.value as number;
+    return h(
+      "span",
+      { style: { color: "#047857", fontWeight: 600 } },
+      `$${value.toLocaleString("en-US", { minimumFractionDigits: 2 })}`,
+    );
+  },
+
+  // Status badge
+  statusBadge: (params: CellRendererParams) => {
+    const status = params.value as Order["status"];
+    const colors: Record<string, { bg: string; text: string }> = {
+      pending: { bg: "#fef3c7", text: "#92400e" },
+      shipped: { bg: "#dbeafe", text: "#1e40af" },
+      delivered: { bg: "#dcfce7", text: "#166534" },
+      cancelled: { bg: "#fee2e2", text: "#991b1b" },
+    };
+    const color = colors[status] ?? { bg: "#f3f4f6", text: "#374151" };
+
+    return h(
+      "span",
+      {
+        style: {
+          backgroundColor: color.bg,
+          color: color.text,
+          padding: "2px 8px",
+          borderRadius: "12px",
+          fontSize: "12px",
+          fontWeight: 600,
+        },
+      },
+      status.toUpperCase(),
+    );
+  },
+
+  // Bold text
+  bold: (params: CellRendererParams) =>
+    h("strong", String(params.value ?? "")),
+};
+
+const columns: ColumnDefinition[] = [
+  {
+    field: "id",
+    cellDataType: "number",
+    width: 80,
+    headerName: "ID",
+    cellRenderer: "bold",
+  },
+  {
+    field: "customer",
+    cellDataType: "text",
+    width: 200,
+    headerName: "Customer",
+  },
+  {
+    field: "total",
+    cellDataType: "number",
+    width: 120,
+    headerName: "Total",
+    cellRenderer: "currency",
+  },
+  {
+    field: "status",
+    cellDataType: "text",
+    width: 120,
+    headerName: "Status",
+    cellRenderer: "statusBadge",
+  },
+];
+
+const orders: Order[] = [
+  { id: 1, customer: "Acme Corp", total: 1250.0, status: "shipped" },
+  { id: 2, customer: "Globex Inc", total: 890.5, status: "pending" },
+  { id: 3, customer: "Initech", total: 2100.75, status: "delivered" },
+];
+</script>
+
+<template>
+  <div style="width: 100%; height: 400px">
+    <GpGrid
+      :columns="columns"
+      :row-data="orders"
+      :row-height="40"
+      :cell-renderers="cellRenderers"
+    />
+  </div>
+</template>
+```
+
+### Editable Cells with Custom Editors
+
+```vue
+<script setup lang="ts">
+import { h, ref as vueRef } from "vue";
+import {
+  GpGrid,
+  createClientDataSource,
+  type ColumnDefinition,
+  type EditRendererParams,
+  type VueEditRenderer,
+} from "gp-grid-vue";
+
+interface Task {
+  id: number;
+  title: string;
+  priority: "low" | "medium" | "high";
+  completed: boolean;
+}
+
+// Custom select editor for priority field
+const editRenderers: Record<string, VueEditRenderer> = {
+  prioritySelect: (params: EditRendererParams) => {
+    return h("select", {
+      autofocus: true,
+      value: params.initialValue as string,
+      onChange: (e: Event) => {
+        const target = e.target as HTMLSelectElement;
+        params.onValueChange(target.value);
+      },
+      onBlur: () => params.onCommit(),
+      onKeydown: (e: KeyboardEvent) => {
+        if (e.key === "Enter") params.onCommit();
+        if (e.key === "Escape") params.onCancel();
+      },
+      style: {
+        width: "100%",
+        height: "100%",
+        border: "none",
+        outline: "none",
+        padding: "0 8px",
+      },
+    }, [
+      h("option", { value: "low" }, "Low"),
+      h("option", { value: "medium" }, "Medium"),
+      h("option", { value: "high" }, "High"),
+    ]);
+  },
+
+  checkbox: (params: EditRendererParams) =>
+    h("input", {
+      type: "checkbox",
+      autofocus: true,
+      checked: params.initialValue as boolean,
+      onChange: (e: Event) => {
+        const target = e.target as HTMLInputElement;
+        params.onValueChange(target.checked);
+        params.onCommit();
+      },
+      style: { width: "20px", height: "20px" },
+    }),
+};
+
+const columns: ColumnDefinition[] = [
+  { field: "id", cellDataType: "number", width: 60, headerName: "ID" },
+  {
+    field: "title",
+    cellDataType: "text",
+    width: 300,
+    headerName: "Title",
+    editable: true, // Uses default text input
+  },
+  {
+    field: "priority",
+    cellDataType: "text",
+    width: 120,
+    headerName: "Priority",
+    editable: true,
+    editRenderer: "prioritySelect", // Custom editor
+  },
+  {
+    field: "completed",
+    cellDataType: "boolean",
+    width: 100,
+    headerName: "Done",
+    editable: true,
+    editRenderer: "checkbox", // Custom editor
+  },
+];
+
+const tasks: Task[] = [
+  { id: 1, title: "Write documentation", priority: "high", completed: false },
+  { id: 2, title: "Fix bugs", priority: "medium", completed: true },
+  { id: 3, title: "Add tests", priority: "low", completed: false },
+];
+
+const dataSource = createClientDataSource(tasks);
+</script>
+
+<template>
+  <div style="width: 600px; height: 300px">
+    <GpGrid
+      :columns="columns"
+      :data-source="dataSource"
+      :row-height="40"
+      :edit-renderers="editRenderers"
+    />
+  </div>
+</template>
+```
+
+### Dark Mode
+
+```vue
+<template>
+  <GpGrid :columns="columns" :row-data="data" :row-height="36" :dark-mode="true" />
+</template>
+```
+
+## API Reference
+
+### GpGridProps
+
+| Prop              | Type                                | Default     | Description                                                 |
+| ----------------- | ----------------------------------- | ----------- | ----------------------------------------------------------- |
+| `columns`         | `ColumnDefinition[]`                | required    | Column definitions                                          |
+| `dataSource`      | `DataSource<TData>`                 | -           | Data source for fetching data                               |
+| `rowData`         | `TData[]`                           | -           | Alternative: raw data array (wrapped in client data source) |
+| `rowHeight`       | `number`                            | required    | Height of each row in pixels                                |
+| `headerHeight`    | `number`                            | `rowHeight` | Height of header row                                        |
+| `overscan`        | `number`                            | `3`         | Number of rows to render outside viewport                   |
+| `sortingEnabled`  | `boolean`                           | `true`      | Enable column sorting                                       |
+| `darkMode`        | `boolean`                           | `false`     | Enable dark theme                                           |
+| `wheelDampening`  | `number`                            | `0.1`       | Scroll wheel sensitivity (0-1)                              |
+| `cellRenderers`   | `Record<string, VueCellRenderer>`   | `{}`        | Cell renderer registry                                      |
+| `editRenderers`   | `Record<string, VueEditRenderer>`   | `{}`        | Edit renderer registry                                      |
+| `headerRenderers` | `Record<string, VueHeaderRenderer>` | `{}`        | Header renderer registry                                    |
+| `cellRenderer`    | `VueCellRenderer`                   | -           | Global fallback cell renderer                               |
+| `editRenderer`    | `VueEditRenderer`                   | -           | Global fallback edit renderer                               |
+| `headerRenderer`  | `VueHeaderRenderer`                 | -           | Global fallback header renderer                             |
+
+### ColumnDefinition
+
+| Property         | Type           | Description                                                         |
+| ---------------- | -------------- | ------------------------------------------------------------------- |
+| `field`          | `string`       | Property path in row data (supports dot notation: `"address.city"`) |
+| `colId`          | `string`       | Unique column ID (defaults to `field`)                              |
+| `cellDataType`   | `CellDataType` | `"text"` \| `"number"` \| `"boolean"` \| `"date"` \| `"object"`     |
+| `width`          | `number`       | Column width in pixels                                              |
+| `headerName`     | `string`       | Display name in header (defaults to `field`)                        |
+| `editable`       | `boolean`      | Enable cell editing                                                 |
+| `cellRenderer`   | `string`       | Key in `cellRenderers` registry                                     |
+| `editRenderer`   | `string`       | Key in `editRenderers` registry                                     |
+| `headerRenderer` | `string`       | Key in `headerRenderers` registry                                   |
+
+### Renderer Types
+
+```typescript
+import type { VNode } from "vue";
+
+// Cell renderer receives these params
+interface CellRendererParams {
+  value: CellValue; // Current cell value
+  rowData: Row; // Full row data
+  column: ColumnDefinition; // Column definition
+  rowIndex: number; // Row index
+  colIndex: number; // Column index
+  isActive: boolean; // Is this the active cell?
+  isSelected: boolean; // Is this cell in selection?
+  isEditing: boolean; // Is this cell being edited?
+}
+
+// Vue cell renderer - can return VNode or string
+type VueCellRenderer = (params: CellRendererParams) => VNode | string | null;
+
+// Edit renderer receives additional callbacks
+interface EditRendererParams extends CellRendererParams {
+  initialValue: CellValue;
+  onValueChange: (newValue: CellValue) => void;
+  onCommit: () => void;
+  onCancel: () => void;
+}
+
+// Vue edit renderer - returns VNode for edit input
+type VueEditRenderer = (params: EditRendererParams) => VNode | null;
+
+// Header renderer params
+interface HeaderRendererParams {
+  column: ColumnDefinition;
+  colIndex: number;
+  sortDirection?: "asc" | "desc";
+  sortIndex?: number; // For multi-column sort
+  onSort: (direction: "asc" | "desc" | null, addToExisting: boolean) => void;
+}
+
+// Vue header renderer
+type VueHeaderRenderer = (params: HeaderRendererParams) => VNode | string | null;
+```
+
+## Keyboard Shortcuts
+
+| Key                | Action                            |
+| ------------------ | --------------------------------- |
+| Arrow keys         | Navigate between cells            |
+| Shift + Arrow      | Extend selection                  |
+| Enter              | Start editing / Commit edit       |
+| Escape             | Cancel edit / Clear selection     |
+| Tab                | Commit and move right             |
+| Shift + Tab        | Commit and move left              |
+| F2                 | Start editing                     |
+| Delete / Backspace | Start editing with empty value    |
+| Ctrl + A           | Select all                        |
+| Ctrl + C           | Copy selection to clipboard       |
+| Any character      | Start editing with that character |
+
+## Styling
+
+The grid injects its own styles automatically. The main container uses these CSS classes:
+
+- `.gp-grid-container` - Main container
+- `.gp-grid-container--dark` - Dark mode modifier
+- `.gp-grid-header` - Header row container
+- `.gp-grid-header-cell` - Individual header cell
+- `.gp-grid-row` - Row container
+- `.gp-grid-cell` - Cell container
+- `.gp-grid-cell--active` - Active cell
+- `.gp-grid-cell--selected` - Selected cell
+- `.gp-grid-cell--editing` - Cell in edit mode
+- `.gp-grid-filter-row` - Filter row container
+- `.gp-grid-filter-input` - Filter input field
+- `.gp-grid-fill-handle` - Fill handle element
+
+## Donations
+
+Keeping this library requires effort and passion, I'm a full time engineer employed on other project and I'm trying my best to keep this work free! For all the features.
+
+If you think this project helped you achieve your goals, it's hopefully worth a beer! 🍻
+
+<div align="center">
+
+### Paypal
+
+[![Paypal QR Code](../../public/images/donazione_paypal.png "Paypal QR Code donation")](https://www.paypal.com/donate/?hosted_button_id=XCNMG6BR4ZMLY)
+
+[https://www.paypal.com/donate/?hosted_button_id=XCNMG6BR4ZMLY](https://www.paypal.com/donate/?hosted_button_id=XCNMG6BR4ZMLY)
+
+### Bitcoin
+
+[![Bitcoin QR Donation](../../public/images/bc1qcukwmzver59eyqq442xyzscmxavqjt568kkc9m.png "Bitcoin QR Donation")](bitcoin:bc1qcukwmzver59eyqq442xyzscmxavqjt568kkc9m)
+
+bitcoin:bc1qcukwmzver59eyqq442xyzscmxavqjt568kkc9m
+
+### Lightning Network
+
+[![Lightning Network QR Donation](../../public/images/lightning.png "Lightning Network QR Donation")](lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhx6rpvanhjetdvfjhyvf4xs0xu5p7)
+
+lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhx6rpvanhjetdvfjhyvf4xs0xu5p7
+
+</div>

package/dist/index.d.ts

@@ -333,11 +333,11 @@ type BatchInstructionListener = (instructions: GridInstruction[]) => void;
 //#endregion
 //#region ../core/src/types/renderers.d.ts
 /** Cell renderer params */
-interface CellRendererParams {
+interface CellRendererParams<TData extends Row = Row> {
   /** Cell value */
   value: CellValue;
   /** Row data */
-  rowData: Row;
+  rowData: TData;
   /** Column definition */
   column: ColumnDefinition;
   /** Row index */
@@ -352,7 +352,7 @@ interface CellRendererParams {
   isEditing: boolean;
 }
 /** Edit renderer params */
-interface EditRendererParams extends CellRendererParams {
+interface EditRendererParams<TData extends Row = Row> extends CellRendererParams<TData> {
   /** Initial value */
   initialValue: CellValue;
   /** On value change */
@@ -1193,7 +1193,7 @@ interface UseInputHandlerResult {
 /**
  * Vue composable for handling all input interactions
  */
-declare function useInputHandler(coreRef: ShallowRef<GridCore | null>, containerRef: Ref<HTMLDivElement | null>, columns: ComputedRef<ColumnDefinition[]>, options: UseInputHandlerOptions): UseInputHandlerResult;
+declare function useInputHandler<TData extends Row = Row>(coreRef: ShallowRef<GridCore<TData> | null>, containerRef: Ref<HTMLDivElement | null>, columns: ComputedRef<ColumnDefinition[]>, options: UseInputHandlerOptions): UseInputHandlerResult;
 //#endregion
 //#region src/composables/useAutoScroll.d.ts
 /**
@@ -1422,5 +1422,4 @@ interface RenderHeaderOptions {
  */
 declare function renderHeader(options: RenderHeaderOptions): VNode;
 //#endregion
-export { type CellDataType, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type ColumnDefinition, type ColumnFilterModel, type ContainerBounds, type DataSource, type DataSourceRequest, type DataSourceResponse, type DateFilterCondition, type DragState, type EditRendererParams, type FilterCondition, type FilterModel, type FilterPopupState, _default as GpGrid, _default as default, type GpGridProps, type GridInstruction, type GridState, type HeaderData, type HeaderRendererParams, type KeyEventData, type LocalFilterCondition, type MutableDataSource, type NumberFilterCondition, type PointerEventData, type Row, type RowId, type SelectionState, type SlotData, type SortDirection, type SortModel, type TextFilterCondition, type UseFillHandleOptions, type UseFillHandleResult, type UseFilterConditionsResult, type UseFilterPopupOptions, type UseGpGridOptions, type UseGpGridResult, type UseInputHandlerOptions, type UseInputHandlerResult, type VueCellRenderer, type VueEditRenderer, type VueHeaderRenderer, buildCellClasses, calculateColumnPositions, createClientDataSource, createDataSourceFromArray, createInitialState, createMutableClientDataSource, createServerDataSource, findColumnAtX, getCellValue, getTotalWidth, gridStyles, injectStyles, isCellActive, isCellEditing, isCellInFillPreview, isCellSelected, isRowVisible, renderCell, renderEditCell, renderHeader, useAutoScroll, useFillHandle, useFilterConditions, useFilterPopup, useGpGrid, useGridState, useInputHandler };
-//# sourceMappingURL=index.d.ts.map
+export { type CellDataType, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type ColumnDefinition, type ColumnFilterModel, type ContainerBounds, type DataSource, type DataSourceRequest, type DataSourceResponse, type DateFilterCondition, type DragState, type EditRendererParams, type FilterCondition, type FilterModel, type FilterPopupState, _default as GpGrid, _default as default, type GpGridProps, type GridInstruction, type GridState, type HeaderData, type HeaderRendererParams, type KeyEventData, type LocalFilterCondition, type MutableDataSource, type NumberFilterCondition, type PointerEventData, type Row, type RowId, type SelectionState, type SlotData, type SortDirection, type SortModel, type TextFilterCondition, type UseFillHandleOptions, type UseFillHandleResult, type UseFilterConditionsResult, type UseFilterPopupOptions, type UseGpGridOptions, type UseGpGridResult, type UseInputHandlerOptions, type UseInputHandlerResult, type VueCellRenderer, type VueEditRenderer, type VueHeaderRenderer, buildCellClasses, calculateColumnPositions, createClientDataSource, createDataSourceFromArray, createInitialState, createMutableClientDataSource, createServerDataSource, findColumnAtX, getCellValue, getTotalWidth, gridStyles, injectStyles, isCellActive, isCellEditing, isCellInFillPreview, isCellSelected, isRowVisible, renderCell, renderEditCell, renderHeader, useAutoScroll, useFillHandle, useFilterConditions, useFilterPopup, useGpGrid, useGridState, useInputHandler };