@nu-grid/nuxt 0.1.1

package/dist/runtime/types/cells.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Cell Types System - Public API for custom cell types and editors
+ *
+ * This module exports types for creating custom cell types, editors,
+ * renderers, and filters for NuGrid columns.
+ *
+ * Import from '#nu-grid/cells' in your Nuxt application.
+ */
+import type { TableData } from '@nuxt/ui';
+import type { Column, Row, Table } from '@tanstack/vue-table';
+import type { Component, Ref } from 'vue';
+import type { NuGridEditorConfig, NuGridInteractionRouter } from './_internal/index.js';
+import type { NuGridColumn, NuGridColumnMenuItem } from './column.js';
+import type { NuGridShowErrors } from './validation.js';
+/**
+ * Props for custom cell editor components
+ */
+export interface NuGridCellEditorProps<T extends TableData = TableData> {
+    modelValue: any;
+    cell: any;
+    row: Row<any>;
+    isNavigating: boolean;
+    shouldFocus: boolean;
+    /**
+     * Validation error message from schema validation
+     * When set, the editor should display error styling and optionally show the message
+     */
+    validationError?: string | null;
+    /**
+     * When to show error messages
+     * - 'always': show whenever invalid (default)
+     * - 'hover': show only while hovering
+     * - 'never': never show
+     * @defaultValue 'always'
+     */
+    showValidationErrors?: NuGridShowErrors;
+    /**
+     * Interaction router for registering keyboard handlers
+     * Editors can use this to register keyboard handlers through the router system
+     * instead of managing their own document-level listeners
+     */
+    interactionRouter?: NuGridInteractionRouter<T>;
+}
+/**
+ * Emits for custom cell editor components
+ */
+export interface NuGridCellEditorEmits {
+    (e: 'update:modelValue', value: any): void;
+    (e: 'stop-editing', moveDirection?: 'up' | 'down' | 'next' | 'previous'): void;
+    (e: 'cancel-editing'): void;
+    (e: 'update:isNavigating', value: boolean): void;
+}
+/**
+ * Renderer configuration type - supports multiple formats for flexibility
+ */
+export type NuGridRendererConfig = string | Component | {
+    component: string | Component;
+    props?: Record<string, any>;
+} | ((context: NuGridCellRenderContext) => any);
+/**
+ * Context provided when rendering a cell
+ */
+export interface NuGridCellRenderContext<T = any> {
+    cell: any;
+    row: Row<T>;
+    getValue: () => any;
+    column: Column<T, unknown>;
+    table: Table<T>;
+}
+/**
+ * Filter operator definition
+ */
+export interface NuGridFilterOperator {
+    /** Unique identifier for the operator */
+    value: string;
+    /** Human-readable label */
+    label: string;
+    /** Filter function that determines if a row matches */
+    filterFn: (row: Row<any>, columnId: string, filterValue: any, operatorValue: string) => boolean;
+}
+/**
+ * Filter configuration for a cell type
+ */
+export interface NuGridFilterConfig {
+    /** Filter control component (rendered in column menu or header) */
+    component?: Component | string;
+    /** Props to pass to filter component */
+    props?: Record<string, any>;
+    /** Default filter value */
+    defaultValue?: any;
+    /** Filter operator options (e.g., 'equals', 'contains', 'greaterThan', etc.) */
+    operators?: NuGridFilterOperator[];
+    /** Default operator to use */
+    defaultOperator?: string;
+}
+/**
+ * Context provided to filter components
+ */
+export interface NuGridFilterContext<T extends TableData = TableData> {
+    /** The column being filtered */
+    column: Column<T, unknown>;
+    /** Current filter value (reactive) */
+    filterValue: Ref<any>;
+    /** Set the filter value */
+    setFilterValue: (value: any) => void;
+    /** Clear the filter */
+    clearFilter: () => void;
+    /** Whether a filter is currently active */
+    isFiltered: boolean;
+    /** Table API instance */
+    table: Table<T>;
+}
+/**
+ * Context provided to cell types
+ * Provides access to cell, row, column, and utility functions
+ */
+export interface NuGridCellTypeContext<T extends TableData = TableData> {
+    /** The cell being operated on */
+    cell: any;
+    /** The row containing the cell */
+    row: Row<T>;
+    /** Column definition */
+    columnDef: any;
+    /** Column instance */
+    column: Column<T, unknown>;
+    /** Current cell value */
+    getValue: () => any;
+    /** Whether the cell is currently focused */
+    isFocused: boolean;
+    /** Whether editing is enabled for this cell */
+    canEdit: boolean;
+    /** Data array reference (for direct updates) */
+    data: T[];
+    /** TanStack table API */
+    tableApi: Table<T>;
+    /** Start editing the cell */
+    startEditing: (initialValue?: any) => void;
+    /** Stop editing and save value */
+    stopEditing: (newValue: any, moveDirection?: 'up' | 'down' | 'next' | 'previous') => void;
+    /** Emit cell value change event */
+    emitChange: (oldValue: any, newValue: any) => void;
+}
+/**
+ * Result from a cell type's keyboard handler
+ */
+export interface NuGridCellTypeKeyboardResult {
+    /** Whether the cell type handled this key event */
+    handled: boolean;
+    /** Whether to prevent default behavior */
+    preventDefault?: boolean;
+    /** Whether to stop event propagation */
+    stopPropagation?: boolean;
+}
+/**
+ * Result from validation function
+ */
+export interface NuGridValidationResult {
+    /** Whether the value is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    message?: string;
+    /** Detailed validation issues (for schema validation) */
+    issues?: ReadonlyArray<{
+        message: string;
+        path?: ReadonlyArray<PropertyKey | {
+            key: PropertyKey;
+        }>;
+    }>;
+}
+/**
+ * Cell type interface
+ * Comprehensive interface for defining custom cell types with editors, renderers, filters, validation, and more
+ *
+ * @example
+ * // Custom rating cell type
+ * const ratingCellType: NuGridCellType = {
+ *   name: 'rating',
+ *   displayName: 'Rating',
+ *   description: '1-5 star rating column',
+ *   editor: RatingEditor,
+ *   renderer: RatingRenderer,
+ *   filter: {
+ *     component: RatingFilter,
+ *     operators: [
+ *       { value: 'equals', label: 'Equals', filterFn: (row, colId, val) => row.getValue(colId) === val },
+ *       { value: 'gte', label: 'At least', filterFn: (row, colId, val) => row.getValue(colId) >= val }
+ *     ]
+ *   },
+ *   validation: (value) => ({
+ *     valid: value >= 1 && value <= 5,
+ *     message: value < 1 || value > 5 ? 'Rating must be between 1 and 5' : undefined
+ *   }),
+ *   formatter: (value) => `${value} ⭐`,
+ *   keyboardHandler: (event, context) => {
+ *     if (event.key >= '1' && event.key <= '5' && context.isFocused && context.canEdit) {
+ *       const newValue = parseInt(event.key)
+ *       const oldValue = context.getValue()
+ *       context.emitChange(oldValue, newValue)
+ *       return { handled: true, preventDefault: true }
+ *     }
+ *     return { handled: false }
+ *   }
+ * }
+ */
+export interface NuGridCellType<T extends TableData = TableData> {
+    /**
+     * Unique name for this cell type
+     * Used to match against column's cellDataType property
+     */
+    name: string;
+    /**
+     * Human-readable display name for this type
+     * Used in UI elements like filter dropdowns
+     */
+    displayName?: string;
+    /**
+     * Description of what this cell type does
+     * Used for documentation and tooltips
+     */
+    description?: string;
+    /**
+     * Editor component for edit mode
+     * Used when column doesn't specify a custom editor
+     */
+    editor?: NuGridEditorConfig;
+    /**
+     * Renderer component for display mode
+     * Optional - falls back to default cell rendering if not provided
+     */
+    renderer?: NuGridRendererConfig;
+    /**
+     * Custom keyboard handler for non-editing mode
+     * Called when a key is pressed on a focused cell that is not in edit mode
+     * Return { handled: true } to prevent default behavior
+     */
+    keyboardHandler?: (event: KeyboardEvent, context: NuGridCellTypeContext<T>) => NuGridCellTypeKeyboardResult;
+    /**
+     * Validation function for cell values
+     * Called when editing stops to validate the new value
+     */
+    validation?: (value: any, context: NuGridCellTypeContext<T>) => NuGridValidationResult;
+    /**
+     * Formatter function for display values
+     * Transforms the raw value for display purposes
+     */
+    formatter?: (value: any, context: NuGridCellTypeContext<T>) => any;
+    /**
+     * Filter configuration
+     * Defines filter component and operators for this cell type
+     */
+    filter?: NuGridFilterConfig;
+    /**
+     * Custom filter function
+     * Overrides default filtering logic for this cell type
+     * If not provided, uses TanStack Table's default filterFn or type's filter operators
+     */
+    filterFn?: (row: Row<T>, columnId: string, filterValue: any) => boolean;
+    /**
+     * Whether filtering is enabled for this cell type
+     * @defaultValue true if filter is provided, false otherwise
+     */
+    enableFiltering?: boolean;
+    /**
+     * Column menu customization
+     * Allows cell types to add or modify column menu items
+     */
+    columnMenuItems?: (defaultItems: NuGridColumnMenuItem<T>[], column: Column<T, unknown>) => NuGridColumnMenuItem<T>[];
+    /**
+     * Default cell renderer function
+     * Used if renderer component is not provided
+     * Falls back to TanStack Table's default cell rendering
+     */
+    defaultCellRenderer?: (context: NuGridCellRenderContext<T>) => any;
+    /**
+     * Lifecycle hook called when a cell is created
+     * Useful for initialization or setup
+     */
+    onCellCreated?: (cell: any, context: NuGridCellTypeContext<T>) => void;
+    /**
+     * Lifecycle hook called when a cell value changes
+     * Useful for side effects or data synchronization
+     */
+    onValueChanged?: (oldValue: any, newValue: any, context: NuGridCellTypeContext<T>) => void;
+    /**
+     * Default column definition properties
+     * Applied to columns using this cell type
+     * Can be overridden by explicit column definition
+     */
+    defaultColumnDef?: Partial<NuGridColumn<T>>;
+}
+export { useNuGridCellEditor } from '../composables/useNuGridCellEditor.js';
+export { nuGridCellTypeRegistry, useNuGridCellTypeRegistry, } from '../composables/useNuGridCellTypeRegistry.js';

package/dist/runtime/types/cells.js

@@ -0,0 +1,5 @@
+export { useNuGridCellEditor } from "../composables/useNuGridCellEditor.js";
+export {
+  nuGridCellTypeRegistry,
+  useNuGridCellTypeRegistry
+} from "../composables/useNuGridCellTypeRegistry.js";

package/dist/runtime/types/column.d.ts

@@ -0,0 +1,248 @@
+import type { DropdownMenuItem, TableColumn, TableData } from '@nuxt/ui';
+import type { Column, Row } from '@tanstack/vue-table';
+import type { NuGridEditorConfig } from './_internal/index.js';
+import type { NuGridValidationResult } from './cells.js';
+import type { NuGridLookupOptions } from './option-groups.js';
+import type { NuGridSortIcon } from './sort-icon.js';
+/**
+ * Extended dropdown menu item for column menus
+ * Adds column parameter to onSelect callback
+ * Supports all DropdownMenuItem types (separator, label, etc.) but extends onSelect for regular items
+ */
+export type NuGridColumnMenuItem<T extends TableData = TableData> = (Omit<DropdownMenuItem, 'onSelect' | 'children'> & {
+    /**
+     * Callback function called when the menu item is selected
+     * @param event The click event (optional)
+     * @param column The column instance (automatically provided by NuGridColumnMenu)
+     */
+    onSelect?: (event?: Event, column?: Column<T, unknown>) => void;
+    /**
+     * Nested menu items (children)
+     */
+    children?: NuGridColumnMenuItem<T>[];
+}) | Extract<DropdownMenuItem, {
+    type: 'separator' | 'label';
+}>;
+/**
+ * Function type for customizing column menu items
+ * Used by both column-level `columnMenuItems` callbacks and grid-level `getColumnMenuItems`
+ * @param defaultItems The default menu items for the column
+ * @param column The column instance
+ * @returns Custom menu items array
+ */
+export type NuGridColumnMenuItemsCallback<T extends TableData = TableData> = (defaultItems: NuGridColumnMenuItem<T>[], column: Column<T, unknown>) => NuGridColumnMenuItem<T>[];
+/**
+ * Extended column type with editor support
+ */
+export type NuGridColumn<T extends TableData> = TableColumn<T> & {
+    /**
+     * Editor configuration for the column cell
+     * Can be specified as:
+     * - String: Component name (e.g., 'NuGridCellEditorRange')
+     * - Object: { component: 'ComponentName', props: { min: 0, max: 100 } }
+     * - Function: Custom render function for advanced cases
+     * @example
+     * // Simple component reference
+     * editor: 'NuGridCellEditorRange'
+     *
+     * // Component with props
+     * editor: { component: 'NuGridCellEditorRange', props: { min: 0, max: 100, step: 5 } }
+     */
+    editor?: NuGridEditorConfig;
+    /**
+     * Controls whether this column is editable
+     * Can be a boolean or a function that receives the row and returns a boolean
+     * @defaultValue true
+     */
+    enableEditing?: boolean | ((row: Row<T>) => boolean);
+    /**
+     * Controls whether this column can receive keyboard focus during navigation
+     * Can be a boolean or a function that receives the row and returns a boolean
+     * When false, the column will be skipped during keyboard navigation (arrows, tab, etc.)
+     * @defaultValue true
+     */
+    enableFocusing?: boolean | ((row: Row<T>) => boolean);
+    /**
+     * Data type for the cell, determines which default editor to use
+     * Built-in types: 'text', 'number', 'date', 'boolean', 'selection', 'action-menu', 'lookup'
+     * Custom types can be registered via cellTypes prop
+     * @defaultValue 'text'
+     */
+    cellDataType?: string;
+    /**
+     * Lookup/dropdown configuration for cells using cellDataType: 'lookup'
+     * Provides a dropdown selection interface using Nuxt UI's SelectMenu
+     * @example
+     * {
+     *   items: [
+     *     { value: 'active', label: 'Active' },
+     *     { value: 'inactive', label: 'Inactive' }
+     *   ],
+     *   valueKey: 'value',
+     *   labelKey: 'label',
+     *   searchable: true
+     * }
+     */
+    lookup?: NuGridLookupOptions;
+    /**
+     * Sort icon configuration for this column's header
+     * Overrides the grid-level sortIcons configuration
+     * @example
+     * // Use custom icons for this column
+     * sortIcons: {
+     *   unsorted: 'i-lucide-chevrons-up-down',
+     *   asc: 'i-lucide-chevron-up',
+     *   desc: 'i-lucide-chevron-down',
+     *   position: 'inline'
+     * }
+     */
+    sortIcons?: NuGridSortIcon;
+    /**
+     * Override the default cell rendering behavior
+     * When true, indicates that the cell uses a custom renderer and should bypass default rendering logic
+     * @defaultValue false
+     */
+    overrideCellRender?: boolean;
+    /**
+     * Controls whether the column menu is enabled for this column
+     * @defaultValue true
+     */
+    enableColumnMenu?: boolean;
+    /**
+     * Controls whether this column can be reordered via drag and drop
+     * @defaultValue true
+     */
+    enableReordering?: boolean;
+    /**
+     * Controls whether the column visibility chooser appears in the column menu
+     * Column-level setting takes precedence over grid-level `showColumnVisibility`
+     * @defaultValue true
+     */
+    showColumnVisibility?: boolean;
+    /**
+     * Custom menu items for the column menu
+     * Can be either:
+     * - An array of menu items (replaces default items)
+     * - A callback function that receives default items and returns custom items
+     * If not provided, default menu items are used
+     * @example
+     * // Replace with custom items
+     * columnMenuItems: [
+     *   { label: 'Custom Action', icon: 'i-lucide-star', onSelect: (event, column) => console.log(column?.id) }
+     * ]
+     * @example
+     * // Modify default items
+     * columnMenuItems: (defaultItems) => [
+     *   ...defaultItems,
+     *   { type: 'separator' },
+     *   { label: 'Custom Action', icon: 'i-lucide-star', onSelect: (event, column) => console.log(column?.id) }
+     * ]
+     */
+    columnMenuItems?: NuGridColumnMenuItem<T>[] | ((defaultItems: NuGridColumnMenuItem<T>[], column?: Column<T, unknown>) => NuGridColumnMenuItem<T>[]);
+    /**
+     * Controls whether this column's editor is shown when the user clicks "Add New"
+     * When false, the column will be hidden in the add new row form
+     * @defaultValue true
+     */
+    showNew?: boolean;
+    /**
+     * Controls whether this column is required when adding a new row
+     * Can be a boolean or a function that returns a boolean
+     * @defaultValue false
+     * @example
+     * // Simple boolean
+     * requiredNew: true
+     *
+     * @example
+     * // Function for dynamic requirement
+     * requiredNew: () => someCondition
+     */
+    requiredNew?: boolean | (() => boolean);
+    /**
+     * Validation function for the new row value
+     * Called when the user attempts to add a new row with a value for this column
+     * @param value The current value being attempted by the user
+     * @returns NuGridValidationResult, boolean, or string (error message)
+     * @example
+     * // Return NuGridValidationResult
+     * validateNew: (value) => ({
+     *   valid: value.length > 0,
+     *   message: 'Name is required'
+     * })
+     *
+     * @example
+     * // Return boolean
+     * validateNew: (value) => value > 0
+     *
+     * @example
+     * // Return string (error message) or undefined/null (valid)
+     * validateNew: (value) => value ? undefined : 'Value is required'
+     */
+    validateNew?: (value: any) => NuGridValidationResult | boolean | string | undefined | null;
+    /**
+     * Controls whether text in this column should wrap instead of being truncated
+     * When true, cell content will wrap to multiple lines
+     * When false or undefined, text will be truncated with ellipsis
+     * @defaultValue false
+     */
+    wrapText?: boolean;
+    /**
+     * Alternate field in the row data to use as the tooltip value
+     * When set, tooltip always shows (ignores truncatedOnly setting for this column)
+     * @example
+     * // Show 'fullDescription' field as tooltip for 'title' column
+     * { accessorKey: 'title', tooltipField: 'fullDescription' }
+     */
+    tooltipField?: string;
+    /**
+     * Function to generate custom tooltip content for cells in this column
+     * Takes precedence over tooltipField
+     * When set, tooltip always shows (ignores truncatedOnly setting for this column)
+     * @param row The row data
+     * @returns The tooltip text to display
+     * @example
+     * // Generate tooltip from multiple fields
+     * tooltipValue: (row) => `${row.name} - ${row.department}`
+     */
+    tooltipValue?: (row: T) => string;
+    /**
+     * Whether to show a tooltip on the column header
+     * Useful for showing full header text when header is truncated
+     * @defaultValue false
+     */
+    tooltipHeader?: boolean;
+    /**
+     * Function to generate custom tooltip content for the column header
+     * When set, tooltipHeader is automatically enabled
+     * @returns The tooltip text for the header
+     * @example
+     * // Custom header tooltip
+     * tooltipHeaderValue: () => 'Full column description or help text'
+     */
+    tooltipHeaderValue?: () => string;
+    /**
+     * The visual row index this column should appear on in multi-row mode
+     * Only used when `multiRow.enabled` is true on the grid
+     * Columns on the same row are rendered left-to-right in their defined order
+     * @defaultValue 0
+     * @example
+     * // Place this column on the second visual row
+     * row: 1
+     */
+    row?: number;
+    /**
+     * Number of column slots to span in aligned multi-row mode
+     * Only used when `multiRow.alignColumns` is true
+     * - Number: Span that many columns from row 0
+     * - '*': Span all remaining columns (fills to the end)
+     * @defaultValue 1
+     * @example
+     * // Span 2 column slots
+     * span: 2
+     *
+     * @example
+     * // Span all remaining columns
+     * span: '*'
+     */
+    span?: number | '*';
+};

package/dist/runtime/types/config.d.ts

@@ -0,0 +1,35 @@
+import type { ComponentConfig } from '@nuxt/ui';
+import type { AppConfig } from 'nuxt/schema';
+import type { nuGridTheme } from '../themes/index.js';
+export type NuGridConfig = ComponentConfig<typeof nuGridTheme, AppConfig, 'table'>;
+export type { NuGridUISlots } from '../composables/_internal/useNuGridUI.js';
+/**
+ * Custom theme configuration for app.config.ts
+ */
+export interface NuGridThemeConfig {
+    /** Unique theme identifier */
+    name: string;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Theme description */
+    description?: string;
+    /** Base theme to extend */
+    baseTheme?: string;
+    /** Custom slot classes */
+    slots?: Record<string, string>;
+    /** Custom variants */
+    variants?: Record<string, any>;
+    /** Custom compound variants */
+    compoundVariants?: any[];
+}
+/**
+ * Augment AppConfig to include NuGrid theme configuration
+ */
+declare module 'nuxt/schema' {
+    interface AppConfig {
+        nuGrid?: {
+            /** Custom themes to register */
+            themes?: NuGridThemeConfig[];
+        };
+    }
+}

package/dist/runtime/types/drag-drop.d.ts

@@ -0,0 +1,92 @@
+import type { TableData } from '@nuxt/ui';
+import type { Header, Row } from '@tanstack/vue-table';
+import type { MaybeRef, Ref } from 'vue';
+/**
+ * Event payload for row drag events
+ */
+export interface RowDragEvent<T extends TableData = TableData> {
+    /**
+     * The row data that was dragged
+     */
+    row: T;
+    /**
+     * Original index in the data array before drag
+     */
+    originalIndex: number;
+    /**
+     * New index in the data array after drop
+     */
+    newIndex: number;
+    /**
+     * Grid ID where the drag originated (for cross-grid dragging)
+     */
+    sourceGridId?: string;
+    /**
+     * Grid ID where the item was dropped (for cross-grid dragging)
+     */
+    targetGridId?: string;
+    /**
+     * Group value where the drag originated (for grouped tables)
+     */
+    sourceGroup?: string;
+    /**
+     * Group value where the item was dropped (for grouped tables)
+     */
+    targetGroup?: string;
+    /**
+     * Position change: positive means moved down, negative means moved up
+     */
+    positionChange: number;
+    /**
+     * Whether the row was moved to a different group
+     */
+    groupChanged: boolean;
+    /**
+     * Whether the row was moved to a different grid
+     */
+    gridChanged: boolean;
+    /**
+     * The drop position relative to target ('before' or 'after')
+     */
+    dropPosition: 'before' | 'after';
+}
+/**
+ * Type for nugrid-dragfns injection
+ * Provides column drag and drop functionality
+ */
+export interface NuGridColumnDragDrop<T extends TableData = TableData> {
+    draggedColumnId: MaybeRef<string | null>;
+    dropTargetColumnId: MaybeRef<string | null>;
+    dropPosition: MaybeRef<'left' | 'right'>;
+    isDraggingOutside: Ref<boolean>;
+    handleColumnDragStart: (e: DragEvent, columnId: string) => void;
+    handleColumnDragOver: (e: DragEvent, columnId: string) => void;
+    handleColumnDrop: (e: DragEvent, columnId: string) => void;
+    handleColumnDragEnd: () => void;
+    handleColumnDragLeave: (e: DragEvent) => void;
+    handleColumnDragEnter: () => void;
+    isHeaderDraggable: (header: Header<T, any>) => boolean;
+    headerDragHandleProps: (header: Header<T, any>) => Record<string, unknown>;
+    headerDragProps: (header: Header<T, any>) => Record<string, unknown>;
+}
+/**
+ * Type for nugrid-rowdragfns injection
+ * Provides row drag and drop functionality
+ */
+export interface NuGridRowDragDrop<T extends TableData = TableData> {
+    draggedRowId: Ref<string | null>;
+    draggedRowData: Ref<T | null>;
+    dropTargetRowId: Ref<string | null>;
+    dropPosition: Ref<'before' | 'after'>;
+    dragSourceGridId: Ref<string | null>;
+    isDraggingOutside: Ref<boolean>;
+    handleRowDragStart: (e: DragEvent, row: Row<T>) => void;
+    handleRowDragOver: (e: DragEvent, row: Row<T>) => void;
+    handleRowDrop: (e: DragEvent, row: Row<T>) => void;
+    handleRowDragEnd: () => void;
+    handleRowDragLeave: (e: DragEvent) => void;
+    handleRowDragEnter: () => void;
+    isRowDraggable: (row: Row<T>) => boolean;
+    rowDragHandleProps: (row: Row<T>) => Record<string, unknown>;
+    rowDragProps: (row: Row<T>) => Record<string, unknown>;
+}