@nu-grid/nuxt 0.1.1

package/dist/runtime/types/tanstack-table.d.ts

@@ -0,0 +1,126 @@
+import type { Column, Row, RowData } from '@tanstack/vue-table'
+import type { NuGridEditorConfig } from './_internal'
+import type { NuGridColumnMenuItem } from './column'
+import type { NuGridSortIcon, NuGridValidationResult } from './index'
+
+/**
+ * Module augmentation for TanStack Table to add NuGrid custom column properties.
+ * This extends the ColumnDefBase interface to add custom properties directly
+ * to column definitions, avoiding the need to access them via the `meta` property.
+ *
+ * @see https://tanstack.com/table/latest/docs/guide/column-defs#column-def-types
+ */
+declare module '@tanstack/vue-table' {
+  interface ColumnDefBase<TData extends RowData, TValue> {
+    /**
+     * 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
+     */
+    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<TData>) => 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<TData>) => boolean)
+
+    /**
+     * Data type for the cell, determines which default editor to use
+     * Built-in types: 'text', 'number', 'date', 'boolean', 'selection', 'action-menu'
+     * Custom types can be registered via cellTypes prop
+     * @defaultValue 'text'
+     */
+    cellDataType?: string
+
+    /**
+     * Sort icon configuration for this column's header
+     * Overrides the grid-level sortIcons configuration
+     */
+    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
+
+    /**
+     * 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
+     */
+    columnMenuItems?:
+      | NuGridColumnMenuItem<TData>[]
+      | ((
+          defaultItems: NuGridColumnMenuItem<TData>[],
+          column?: Column<TData, unknown>,
+        ) => NuGridColumnMenuItem<TData>[])
+
+    /**
+     * 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
+     */
+    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)
+     */
+    validateNew?: (value: any) => NuGridValidationResult | boolean | string | undefined | null
+
+    /**
+     * 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
+     */
+    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
+     */
+    span?: number | '*'
+  }
+}
+
+export {}

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

@@ -0,0 +1,22 @@
+/**
+ * Theme definition for NuGrid
+ */
+export interface NuGridThemeDefinition {
+    /** Unique theme identifier (used in theme prop) */
+    name: string;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Theme description */
+    description?: string;
+    /** The actual theme object (slots, variants, compoundVariants) */
+    theme: {
+        slots: Record<string, string>;
+        variants?: Record<string, any>;
+        compoundVariants?: any[];
+        [key: string]: any;
+    };
+}
+/**
+ * Theme prop type - accepts built-in theme names ('default', 'compact') or custom theme names
+ */
+export type NuGridTheme = 'default' | 'compact' | (string & {});

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

@@ -0,0 +1,94 @@
+import type { TableData } from '@nuxt/ui';
+import type { StandardSchemaV1 } from '../utils/standardSchema.js';
+import type { NuGridRowValidationRule } from './_internal/index.js';
+/**
+ * When validation should run
+ * - 'change': Validate on every keystroke/change (real-time)
+ * - 'blur': Validate when the editor loses focus
+ * - 'submit': Validate only when attempting to save (Enter/Tab/Arrow keys)
+ * - 'reward': Show errors only after blur/submission (punish late),
+ *   but clear errors immediately when value becomes valid (reward early).
+ *   This provides a balanced UX: don't interrupt users while typing valid input,
+ *   but give immediate positive feedback when correcting errors.
+ */
+export type NuGridValidateOn = 'change' | 'blur' | 'submit' | 'reward';
+/**
+ * When to show validation error messages
+ * - 'never': Never show errors
+ * - 'hover': Show only while the editor is hovered
+ * - 'always': Show whenever invalid (default)
+ */
+export type NuGridShowErrors = 'never' | 'hover' | 'always';
+/**
+ * What to do when validation fails and user tries to leave the editor
+ * - 'block': Prevent leaving cell until value is valid (default)
+ * - 'revert': Revert to original value and allow navigation
+ * - 'warn': Allow navigation but show warning
+ */
+export type NuGridOnInvalid = 'block' | 'revert' | 'warn';
+/**
+ * Base validation configuration options
+ */
+interface NuGridValidationOptionsBase {
+    /**
+     * When to run validation
+     * - 'change': Validate on every keystroke (real-time)
+     * - 'blur': Validate when the editor loses focus
+     * - 'submit': Validate only when attempting to save
+     * - 'reward': Punish late (show after blur), reward early (clear when valid)
+     * @defaultValue 'reward'
+     */
+    validateOn?: NuGridValidateOn;
+    /**
+     * When to show error messages
+     * - 'always': Show whenever invalid (default)
+     * - 'hover': Show only while the editor is hovered
+     * - 'never': Never show errors
+     * @defaultValue 'always'
+     */
+    showErrors?: NuGridShowErrors;
+    /**
+     * What to do when validation fails and user tries to leave
+     * - 'block': Prevent leaving until valid (default)
+     * - 'revert': Revert to original value and allow navigation
+     * - 'warn': Allow navigation but show warning
+     * @defaultValue 'block'
+     */
+    onInvalid?: NuGridOnInvalid;
+    /**
+     * Whether to validate when adding a new row
+     * @defaultValue true
+     */
+    validateOnAddRow?: boolean;
+    /**
+     * Icon name to display with error messages
+     * @defaultValue 'i-lucide-alert-circle'
+     */
+    icon?: string;
+}
+/**
+ * Validation configuration options for NuGrid props
+ */
+export interface NuGridValidationOptions<T extends TableData = TableData> extends NuGridValidationOptionsBase {
+    /**
+     * The Standard Schema v1 validation schema
+     * @see https://standardschema.dev
+     */
+    schema?: StandardSchemaV1<T>;
+    /**
+     * Row-level validation rules
+     * These rules validate relationships between fields in a row
+     * They run after cell-level schema validation passes
+     *
+     * @example
+     * rowRules: [
+     *   (row) => ({
+     *     valid: !(row.department === 'Engineering' && row.salary < 100000),
+     *     message: 'Engineering employees must have salary >= $100,000',
+     *     failedFields: ['salary']
+     *   })
+     * ]
+     */
+    rowRules?: NuGridRowValidationRule<T>[];
+}
+export {};

package/dist/runtime/utils/columnHelper.d.ts

@@ -0,0 +1,208 @@
+import type { TableData } from '@nuxt/ui';
+import type { ColumnDefTemplate, StringOrTemplateHeader } from '@tanstack/vue-table';
+import type { NuGridColumn } from '../types/column.js';
+/**
+ * Properties for accessor columns (columns that map to a data field)
+ * Omits 'accessorKey' since it's provided separately for type safety
+ */
+export type AccessorColumnDef<T extends TableData, TValue = unknown> = Omit<NuGridColumn<T>, 'accessorKey' | 'accessorFn'> & {
+    /**
+     * Custom accessor function for computed values
+     * When provided, this is used instead of direct property access
+     */
+    accessorFn?: (row: T) => TValue;
+};
+/**
+ * Properties for display columns (columns without data accessor)
+ * Used for action columns, custom rendered columns, etc.
+ */
+export type DisplayColumnDef<T extends TableData> = Omit<NuGridColumn<T>, 'accessorKey' | 'accessorFn'> & {
+    /**
+     * Unique identifier for the column (required for display columns)
+     */
+    id: string;
+};
+/**
+ * Properties for column groups
+ */
+export interface GroupColumnDef<T extends TableData> {
+    /**
+     * Unique identifier for the column group
+     */
+    id: string;
+    /**
+     * Header for the column group
+     */
+    header: StringOrTemplateHeader<T, unknown>;
+    /**
+     * Child columns in this group
+     */
+    columns: NuGridColumn<T>[];
+    /**
+     * Optional footer for the column group
+     */
+    footer?: ColumnDefTemplate<{
+        table: any;
+        column: any;
+    }>;
+    /**
+     * Enable resizing for the group
+     */
+    enableResizing?: boolean;
+    /**
+     * Additional metadata
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Column helper instance with methods for creating typed columns
+ */
+export interface ColumnHelper<T extends TableData> {
+    /**
+     * Creates an accessor column that maps to a data field
+     *
+     * @param accessorKey - The key of the field in the data object
+     * @param column - Column configuration options
+     * @returns A fully typed NuGridColumn
+     *
+     * @example
+     * const helper = createColumnHelper<User>()
+     *
+     * helper.accessor('name', {
+     *   header: 'Full Name',
+     *   size: 200,
+     *   enableEditing: true,
+     * })
+     *
+     * @example
+     * // With custom accessor function
+     * helper.accessor('fullName', {
+     *   accessorFn: (row) => `${row.firstName} ${row.lastName}`,
+     *   header: 'Full Name',
+     * })
+     */
+    accessor: <TKey extends keyof T & string>(accessorKey: TKey, column?: AccessorColumnDef<T, T[TKey]>) => NuGridColumn<T>;
+    /**
+     * Creates a display column without a data accessor
+     * Used for action menus, custom buttons, or computed displays
+     *
+     * @param column - Column configuration with required 'id'
+     * @returns A fully typed NuGridColumn
+     *
+     * @example
+     * helper.display({
+     *   id: 'actions',
+     *   header: '',
+     *   size: 50,
+     *   cellDataType: 'action-menu',
+     *   enableEditing: false,
+     *   enableSorting: false,
+     * })
+     */
+    display: (column: DisplayColumnDef<T>) => NuGridColumn<T>;
+    /**
+     * Creates a column group containing multiple columns
+     *
+     * @param group - Group configuration with child columns
+     * @returns A grouped column definition
+     *
+     * @example
+     * helper.group({
+     *   id: 'contact',
+     *   header: 'Contact Information',
+     *   columns: [
+     *     helper.accessor('email', { header: 'Email' }),
+     *     helper.accessor('phone', { header: 'Phone' }),
+     *   ],
+     * })
+     */
+    group: (group: GroupColumnDef<T>) => NuGridColumn<T>;
+}
+/**
+ * Creates a column helper for defining NuGrid columns with full type safety
+ *
+ * Similar to TanStack Table's createColumnHelper, but extended to support
+ * NuGrid-specific features like editing, validation, lookups, and more.
+ *
+ * @returns A column helper instance with accessor, display, and group methods
+ *
+ * @example
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ *   department: string
+ *   salary: number
+ *   isActive: boolean
+ * }
+ *
+ * const columnHelper = createColumnHelper<User>()
+ *
+ * const columns = [
+ *   columnHelper.accessor('id', {
+ *     header: 'ID',
+ *     size: 60,
+ *     enableEditing: false,
+ *   }),
+ *
+ *   columnHelper.accessor('name', {
+ *     header: 'Name',
+ *     size: 200,
+ *     requiredNew: true,
+ *     validateNew: (value) => ({
+ *       valid: value.length >= 2,
+ *       message: 'Name must be at least 2 characters',
+ *     }),
+ *   }),
+ *
+ *   columnHelper.accessor('email', {
+ *     header: 'Email',
+ *     cellDataType: 'text',
+ *     tooltipValue: (row) => `Contact: ${row.email}`,
+ *   }),
+ *
+ *   columnHelper.accessor('department', {
+ *     header: 'Department',
+ *     cellDataType: 'lookup',
+ *     lookup: {
+ *       items: [
+ *         { value: 'engineering', label: 'Engineering' },
+ *         { value: 'marketing', label: 'Marketing' },
+ *         { value: 'sales', label: 'Sales' },
+ *       ],
+ *     },
+ *   }),
+ *
+ *   columnHelper.accessor('salary', {
+ *     header: 'Salary',
+ *     cellDataType: 'number',
+ *     cell: ({ row }) => `$${row.original.salary.toLocaleString()}`,
+ *   }),
+ *
+ *   columnHelper.accessor('isActive', {
+ *     header: 'Active',
+ *     cellDataType: 'boolean',
+ *     size: 80,
+ *   }),
+ *
+ *   columnHelper.display({
+ *     id: 'actions',
+ *     header: '',
+ *     size: 50,
+ *     cellDataType: 'action-menu',
+ *     enableEditing: false,
+ *     enableColumnMenu: false,
+ *   }),
+ *
+ *   // Column groups
+ *   columnHelper.group({
+ *     id: 'personalInfo',
+ *     header: 'Personal Information',
+ *     columns: [
+ *       columnHelper.accessor('name', { header: 'Name' }),
+ *       columnHelper.accessor('email', { header: 'Email' }),
+ *     ],
+ *   }),
+ * ]
+ */
+export declare function createColumnHelper<T extends TableData>(): ColumnHelper<T>;

package/dist/runtime/utils/columnHelper.js

@@ -0,0 +1,23 @@
+export function createColumnHelper() {
+  return {
+    accessor(accessorKey, column = {}) {
+      return {
+        accessorKey,
+        ...column
+      };
+    },
+    display(column) {
+      return column;
+    },
+    group(group) {
+      return {
+        id: group.id,
+        header: group.header,
+        columns: group.columns,
+        footer: group.footer,
+        enableResizing: group.enableResizing,
+        meta: group.meta
+      };
+    }
+  };
+}

package/dist/runtime/utils/excelExport.d.ts

@@ -0,0 +1,63 @@
+import type { Table } from '@tanstack/vue-table';
+import type { NuGridColumn } from '../types/index.js';
+export interface ExcelExportOptions {
+    /**
+     * Filename for the exported file (without extension)
+     * @defaultValue 'export'
+     */
+    filename?: string;
+    /**
+     * Sheet name in the Excel file
+     * @defaultValue 'Sheet1'
+     */
+    sheetName?: string;
+    /**
+     * Whether to include column headers in the export
+     * @defaultValue true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Whether to export only visible columns (respects column visibility state)
+     * @defaultValue true
+     */
+    visibleColumnsOnly?: boolean;
+    /**
+     * Custom column width overrides (column id -> width in characters)
+     */
+    columnWidths?: Record<string, number>;
+}
+/**
+ * Exports grid data to an Excel file
+ * Respects current grid state: column visibility, column order, sorting, and filtering
+ */
+export declare function exportToExcel<T>(tableApi: Table<T>, columns: NuGridColumn<T>[], options?: ExcelExportOptions): Promise<void>;
+export interface GroupedExcelExportOptions extends ExcelExportOptions {
+    /**
+     * Whether to include group header rows
+     * @defaultValue true
+     */
+    includeGroupHeaders?: boolean;
+    /**
+     * Indent data cells under groups (number of spaces)
+     * @defaultValue 2
+     */
+    groupIndent?: number;
+    /**
+     * Format for group header text
+     * @defaultValue '{groupName}: {groupValue} ({count})'
+     */
+    groupHeaderFormat?: string;
+}
+/**
+ * Exports grouped grid data to an Excel file
+ * Preserves group hierarchy with group header rows
+ */
+export declare function exportGroupedToExcel<T>(tableApi: Table<T>, columns: NuGridColumn<T>[], options?: GroupedExcelExportOptions): Promise<void>;
+/**
+ * Exports data array directly to Excel (without table API)
+ */
+export declare function exportDataToExcel<T extends Record<string, unknown>>(data: T[], columns: Array<{
+    key: string;
+    header: string;
+    cellDataType?: string;
+}>, options?: ExcelExportOptions): Promise<void>;