@gridstorm/vue 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,556 @@
+import * as vue from 'vue';
+import { InjectionKey, ShallowRef, Ref } from 'vue';
+import * as _gridstorm_core from '@gridstorm/core';
+import { GridEngine, GridApi, FilterModel, RowNode, SortModelItem, GridEventMap, ColumnDef, GridPlugin, GridConfig } from '@gridstorm/core';
+export { CellEditorDef, CellPosition, ColumnDef, ColumnState, EditingState, FilterModel, GridApi, GridConfig, GridEventMap, GridPlugin, GridState, PinnedPosition, RowNode, SelectionState, SortDirection, SortModelItem } from '@gridstorm/core';
+
+/**
+ * GridStorm Vue 3 component.
+ *
+ * Wraps the headless GridStorm core engine and DOM renderer into a Vue component
+ * with reactive prop watching, event emission, and provide/inject context for
+ * child composables.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { GridStorm } from '@gridstorm/vue';
+ * import { sortingPlugin } from '@gridstorm/plugin-sorting';
+ *
+ * const columns = [
+ *   { field: 'name', headerName: 'Name', sortable: true },
+ *   { field: 'age', headerName: 'Age', width: 100 },
+ * ];
+ * const rowData = [
+ *   { name: 'Alice', age: 30 },
+ *   { name: 'Bob', age: 25 },
+ * ];
+ * </script>
+ *
+ * <template>
+ *   <GridStorm
+ *     :columns="columns"
+ *     :row-data="rowData"
+ *     :plugins="[sortingPlugin()]"
+ *     @grid-ready="(api) => console.log('Grid ready!', api)"
+ *   />
+ * </template>
+ * ```
+ */
+declare const GridStorm: vue.DefineComponent<vue.ExtractPropTypes<{
+    readonly columns: {
+        readonly type: vue.PropType<_gridstorm_core.ColumnDef[]>;
+        readonly required: true;
+    };
+    readonly rowData: {
+        readonly type: vue.PropType<any[]>;
+        readonly required: true;
+    };
+    readonly plugins: {
+        readonly type: vue.PropType<_gridstorm_core.GridPlugin[]>;
+        readonly default: () => never[];
+    };
+    readonly getRowId: {
+        readonly type: vue.PropType<_gridstorm_core.GridConfig["getRowId"]>;
+        readonly default: undefined;
+    };
+    readonly rowHeight: {
+        readonly type: NumberConstructor;
+        readonly default: 40;
+    };
+    readonly headerHeight: {
+        readonly type: NumberConstructor;
+        readonly default: undefined;
+    };
+    readonly theme: {
+        readonly type: StringConstructor;
+        readonly default: "light";
+    };
+    readonly density: {
+        readonly type: StringConstructor;
+        readonly default: "normal";
+    };
+    readonly defaultColDef: {
+        readonly type: vue.PropType<Partial<_gridstorm_core.ColumnDef>>;
+        readonly default: undefined;
+    };
+    readonly paginationPageSize: {
+        readonly type: NumberConstructor;
+        readonly default: undefined;
+    };
+    readonly pagination: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    readonly rowSelection: {
+        readonly type: vue.PropType<"single" | "multiple" | false>;
+        readonly default: undefined;
+    };
+    readonly editType: {
+        readonly type: vue.PropType<"cell" | "fullRow">;
+        readonly default: undefined;
+    };
+    readonly ariaLabel: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
+    readonly height: {
+        readonly type: vue.PropType<number | string>;
+        readonly default: "100%";
+    };
+    readonly width: {
+        readonly type: vue.PropType<number | string>;
+        readonly default: "100%";
+    };
+    readonly containerClass: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, ("gridReady" | "rowDataChanged" | "selectionChanged" | "sortChanged" | "filterChanged" | "cellValueChanged" | "cellClicked" | "cellDoubleClicked" | "rowClicked" | "paginationChanged" | "columnResized")[], "gridReady" | "rowDataChanged" | "selectionChanged" | "sortChanged" | "filterChanged" | "cellValueChanged" | "cellClicked" | "cellDoubleClicked" | "rowClicked" | "paginationChanged" | "columnResized", vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    readonly columns: {
+        readonly type: vue.PropType<_gridstorm_core.ColumnDef[]>;
+        readonly required: true;
+    };
+    readonly rowData: {
+        readonly type: vue.PropType<any[]>;
+        readonly required: true;
+    };
+    readonly plugins: {
+        readonly type: vue.PropType<_gridstorm_core.GridPlugin[]>;
+        readonly default: () => never[];
+    };
+    readonly getRowId: {
+        readonly type: vue.PropType<_gridstorm_core.GridConfig["getRowId"]>;
+        readonly default: undefined;
+    };
+    readonly rowHeight: {
+        readonly type: NumberConstructor;
+        readonly default: 40;
+    };
+    readonly headerHeight: {
+        readonly type: NumberConstructor;
+        readonly default: undefined;
+    };
+    readonly theme: {
+        readonly type: StringConstructor;
+        readonly default: "light";
+    };
+    readonly density: {
+        readonly type: StringConstructor;
+        readonly default: "normal";
+    };
+    readonly defaultColDef: {
+        readonly type: vue.PropType<Partial<_gridstorm_core.ColumnDef>>;
+        readonly default: undefined;
+    };
+    readonly paginationPageSize: {
+        readonly type: NumberConstructor;
+        readonly default: undefined;
+    };
+    readonly pagination: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    readonly rowSelection: {
+        readonly type: vue.PropType<"single" | "multiple" | false>;
+        readonly default: undefined;
+    };
+    readonly editType: {
+        readonly type: vue.PropType<"cell" | "fullRow">;
+        readonly default: undefined;
+    };
+    readonly ariaLabel: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
+    readonly height: {
+        readonly type: vue.PropType<number | string>;
+        readonly default: "100%";
+    };
+    readonly width: {
+        readonly type: vue.PropType<number | string>;
+        readonly default: "100%";
+    };
+    readonly containerClass: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
+}>> & Readonly<{
+    onGridReady?: ((...args: any[]) => any) | undefined;
+    onRowDataChanged?: ((...args: any[]) => any) | undefined;
+    onSelectionChanged?: ((...args: any[]) => any) | undefined;
+    onSortChanged?: ((...args: any[]) => any) | undefined;
+    onFilterChanged?: ((...args: any[]) => any) | undefined;
+    onCellValueChanged?: ((...args: any[]) => any) | undefined;
+    onCellClicked?: ((...args: any[]) => any) | undefined;
+    onCellDoubleClicked?: ((...args: any[]) => any) | undefined;
+    onRowClicked?: ((...args: any[]) => any) | undefined;
+    onPaginationChanged?: ((...args: any[]) => any) | undefined;
+    onColumnResized?: ((...args: any[]) => any) | undefined;
+}>, {
+    readonly getRowId: ((params: _gridstorm_core.GetRowIdParams<any>) => string) | undefined;
+    readonly width: string | number;
+    readonly plugins: _gridstorm_core.GridPlugin<any>[];
+    readonly rowHeight: number;
+    readonly headerHeight: number;
+    readonly theme: string;
+    readonly density: string;
+    readonly defaultColDef: Partial<_gridstorm_core.ColumnDef<any, any>>;
+    readonly paginationPageSize: number;
+    readonly pagination: boolean;
+    readonly rowSelection: false | "single" | "multiple";
+    readonly editType: "cell" | "fullRow";
+    readonly ariaLabel: string;
+    readonly height: string | number;
+    readonly containerClass: string;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * Context value provided to child composables via Vue provide/inject.
+ */
+interface GridContextValue<TData = any> {
+    /** The grid engine instance. */
+    engine: GridEngine<TData>;
+    /** The public grid API. */
+    api: GridApi<TData>;
+}
+/**
+ * Props interface for the GridStorm Vue component.
+ *
+ * @typeParam TData - The type of each row data object.
+ */
+interface GridStormProps<TData = any> {
+    /** Column definitions. */
+    columns: ColumnDef<TData>[];
+    /** Row data array. */
+    rowData: TData[];
+    /** Plugins to install. */
+    plugins?: GridPlugin<TData>[];
+    /** Row ID getter function. */
+    getRowId?: GridConfig<TData>['getRowId'];
+    /** Row height in pixels. */
+    rowHeight?: number;
+    /** Header height in pixels. */
+    headerHeight?: number;
+    /** Theme identifier (e.g., 'light', 'dark'). */
+    theme?: string;
+    /** Density mode (e.g., 'compact', 'normal', 'comfortable'). */
+    density?: string;
+    /** Default column definition applied to all columns. */
+    defaultColDef?: Partial<ColumnDef<TData>>;
+    /** Number of rows per page when pagination is enabled. */
+    paginationPageSize?: number;
+    /** Enable client-side pagination. */
+    pagination?: boolean;
+    /** Row selection mode. */
+    rowSelection?: 'single' | 'multiple' | false;
+    /** Edit type mode. */
+    editType?: 'cell' | 'fullRow';
+    /** ARIA label for the grid root element. */
+    ariaLabel?: string;
+    /** Container height. Default: '100%'. */
+    height?: number | string;
+    /** Container width. Default: '100%'. */
+    width?: number | string;
+    /** Additional CSS class for the container. */
+    containerClass?: string;
+}
+/**
+ * All events emitted by the GridStorm Vue component.
+ */
+interface GridStormEmits<TData = any> {
+    /** Fired when the grid engine is ready and the API is available. */
+    gridReady: [api: GridApi<TData>];
+    /** Fired when row data changes. */
+    rowDataChanged: [event: GridEventMap<TData>['rowData:changed']];
+    /** Fired when the selection changes. */
+    selectionChanged: [event: GridEventMap<TData>['selection:changed']];
+    /** Fired when the sort model changes. */
+    sortChanged: [event: GridEventMap<TData>['column:sort:changed']];
+    /** Fired when the filter model changes. */
+    filterChanged: [event: GridEventMap<TData>['filter:changed']];
+    /** Fired when a cell value is changed via editing. */
+    cellValueChanged: [event: GridEventMap<TData>['cell:valueChanged']];
+    /** Fired when a cell is clicked. */
+    cellClicked: [event: GridEventMap<TData>['cell:clicked']];
+    /** Fired when a cell is double-clicked. */
+    cellDoubleClicked: [event: GridEventMap<TData>['cell:doubleClicked']];
+    /** Fired when a row is clicked. */
+    rowClicked: [event: GridEventMap<TData>['row:clicked']];
+    /** Fired when pagination state changes. */
+    paginationChanged: [event: GridEventMap<TData>['pagination:changed']];
+    /** Fired when a column is resized. */
+    columnResized: [event: GridEventMap<TData>['column:resized']];
+}
+/**
+ * Public methods exposed by the GridStorm component via template refs.
+ *
+ * @typeParam TData - The type of each row data object.
+ */
+interface GridStormExposed<TData = any> {
+    /** Get the GridApi instance. */
+    getApi(): GridApi<TData> | undefined;
+    /** Get the GridEngine instance. */
+    getEngine(): GridEngine<TData> | undefined;
+}
+/**
+ * Return type for the useGridSort composable.
+ */
+interface GridSortResult {
+    /** Current sort model (reactive). */
+    sortModel: SortModelItem[];
+    /** Whether any sort is active (reactive). */
+    isSorted: boolean;
+    /** Set the sort model directly. */
+    setSortModel: (model: SortModelItem[]) => void;
+    /** Toggle sort on a column. */
+    toggleSort: (colId: string, multiSort?: boolean) => void;
+    /** Clear all sorting. */
+    clearSort: () => void;
+}
+/**
+ * Return type for the useGridFilter composable.
+ */
+interface GridFilterResult {
+    /** Current filter model keyed by column ID (reactive). */
+    filterModel: Record<string, FilterModel>;
+    /** Current quick filter text (reactive). */
+    quickFilterText: string;
+    /** Whether any filter is active (reactive). */
+    isFiltered: boolean;
+    /** Set the filter model. */
+    setFilterModel: (model: Record<string, FilterModel>) => void;
+    /** Set quick filter text. */
+    setQuickFilter: (text: string) => void;
+    /** Clear all filters. */
+    clearFilters: () => void;
+}
+/**
+ * Return type for the useGridSelection composable.
+ */
+interface GridSelectionResult<TData = any> {
+    /** Set of selected row IDs (reactive). */
+    selectedRowIds: Set<string>;
+    /** Number of selected rows (reactive). */
+    selectedCount: number;
+    /** Get selected row data objects. */
+    getSelectedRows: () => TData[];
+    /** Get selected RowNode objects. */
+    getSelectedNodes: () => RowNode<TData>[];
+    /** Check if a specific row is selected. */
+    isRowSelected: (rowId: string) => boolean;
+    /** Select all visible rows. */
+    selectAll: () => void;
+    /** Deselect all rows. */
+    deselectAll: () => void;
+}
+/**
+ * Return type for the useGridPagination composable.
+ */
+interface GridPaginationResult {
+    /** Current page (0-indexed, reactive). */
+    currentPage: number;
+    /** Total number of pages (reactive). */
+    totalPages: number;
+    /** Rows per page (reactive). */
+    pageSize: number;
+    /** Total row count after filtering (reactive). */
+    totalRows: number;
+    /** Whether there is a next page (reactive). */
+    hasNextPage: boolean;
+    /** Whether there is a previous page (reactive). */
+    hasPreviousPage: boolean;
+    /** Go to a specific page. */
+    goToPage: (page: number) => void;
+    /** Go to next page. */
+    nextPage: () => void;
+    /** Go to previous page. */
+    previousPage: () => void;
+    /** Go to first page. */
+    firstPage: () => void;
+    /** Go to last page. */
+    lastPage: () => void;
+}
+
+/**
+ * Injection key used internally to provide/inject the grid context.
+ * Uses ShallowRef to avoid deep reactive unwrapping of GridEngine internals
+ * (the Store class has private fields incompatible with Vue's deep proxy typing).
+ */
+declare const GRID_CONTEXT_KEY: InjectionKey<ShallowRef<GridContextValue | null>>;
+/**
+ * Access the GridApi instance from a parent GridStorm component.
+ *
+ * Returns a computed ref that resolves to the GridApi once the grid is initialized.
+ * The ref will be undefined until the grid has mounted.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridApi } from '@gridstorm/vue';
+ *
+ * const api = useGridApi();
+ *
+ * function exportData() {
+ *   const rows = api.value?.getSelectedRows() ?? [];
+ *   console.log('Selected:', rows);
+ * }
+ * </script>
+ * ```
+ */
+declare function useGridApi<TData = any>(): Ref<GridApi<TData> | undefined>;
+/**
+ * Access the GridEngine instance from a parent GridStorm component.
+ *
+ * Primarily useful for advanced use cases that need direct access to
+ * the store, event bus, or command bus.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridEngine } from '@gridstorm/vue';
+ *
+ * const engine = useGridEngine();
+ * </script>
+ * ```
+ */
+declare function useGridEngine<TData = any>(): Ref<GridEngine<TData> | undefined>;
+/**
+ * Reactive sort model state and sort actions.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridSort } from '@gridstorm/vue';
+ *
+ * const { sortModel, isSorted, toggleSort, clearSort } = useGridSort();
+ * </script>
+ *
+ * <template>
+ *   <button @click="toggleSort('name')">Sort by Name</button>
+ *   <button v-if="isSorted" @click="clearSort()">Clear Sort</button>
+ *   <pre>{{ sortModel }}</pre>
+ * </template>
+ * ```
+ */
+declare function useGridSort(): {
+    sortModel: Ref<SortModelItem[]>;
+    isSorted: Ref<boolean>;
+    setSortModel: (model: SortModelItem[]) => void;
+    toggleSort: (colId: string, multiSort?: boolean) => void;
+    clearSort: () => void;
+};
+/**
+ * Reactive filter model state and filter actions.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridFilter } from '@gridstorm/vue';
+ *
+ * const { isFiltered, setQuickFilter, clearFilters } = useGridFilter();
+ * </script>
+ *
+ * <template>
+ *   <input @input="(e) => setQuickFilter((e.target as HTMLInputElement).value)" />
+ *   <button v-if="isFiltered" @click="clearFilters()">Clear Filters</button>
+ * </template>
+ * ```
+ */
+declare function useGridFilter(): {
+    filterModel: Ref<Record<string, FilterModel>>;
+    quickFilterText: Ref<string>;
+    isFiltered: Ref<boolean>;
+    setFilterModel: (model: Record<string, FilterModel>) => void;
+    setQuickFilter: (text: string) => void;
+    clearFilters: () => void;
+};
+/**
+ * Reactive selection state and selection actions.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridSelection } from '@gridstorm/vue';
+ *
+ * const { selectedCount, selectAll, deselectAll, isRowSelected } = useGridSelection();
+ * </script>
+ *
+ * <template>
+ *   <p>{{ selectedCount }} rows selected</p>
+ *   <button @click="selectAll()">Select All</button>
+ *   <button @click="deselectAll()">Deselect All</button>
+ * </template>
+ * ```
+ */
+declare function useGridSelection<TData = any>(): {
+    selectedRowIds: Ref<Set<string>>;
+    selectedCount: Ref<number>;
+    getSelectedRows: () => TData[];
+    getSelectedNodes: () => RowNode<TData>[];
+    isRowSelected: (rowId: string) => boolean;
+    selectAll: () => void;
+    deselectAll: () => void;
+};
+/**
+ * Reactive pagination state and navigation actions.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridPagination } from '@gridstorm/vue';
+ *
+ * const {
+ *   currentPage,
+ *   totalPages,
+ *   hasNextPage,
+ *   hasPreviousPage,
+ *   nextPage,
+ *   previousPage,
+ * } = useGridPagination();
+ * </script>
+ *
+ * <template>
+ *   <div class="pagination">
+ *     <button :disabled="!hasPreviousPage" @click="previousPage()">Prev</button>
+ *     <span>Page {{ currentPage + 1 }} of {{ totalPages }}</span>
+ *     <button :disabled="!hasNextPage" @click="nextPage()">Next</button>
+ *   </div>
+ * </template>
+ * ```
+ */
+declare function useGridPagination(): {
+    currentPage: Ref<number>;
+    totalPages: Ref<number>;
+    pageSize: Ref<number>;
+    totalRows: Ref<number>;
+    hasNextPage: Ref<boolean>;
+    hasPreviousPage: Ref<boolean>;
+    goToPage: (page: number) => void;
+    nextPage: () => void;
+    previousPage: () => void;
+    firstPage: () => void;
+    lastPage: () => void;
+};
+/**
+ * Listen to a specific grid event with automatic cleanup on unmount.
+ *
+ * @param event - The event name from GridEventMap.
+ * @param handler - Callback function invoked when the event fires.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useGridEvent } from '@gridstorm/vue';
+ *
+ * useGridEvent('selection:changed', (e) => {
+ *   console.log('Selection changed:', e.selectedNodes);
+ * });
+ * </script>
+ * ```
+ */
+declare function useGridEvent<TData = any>(event: string, handler: (payload: any) => void): void;
+
+export { GRID_CONTEXT_KEY, type GridContextValue, type GridFilterResult, type GridPaginationResult, type GridSelectionResult, type GridSortResult, GridStorm, type GridStormEmits, type GridStormExposed, type GridStormProps, useGridApi, useGridEngine, useGridEvent, useGridFilter, useGridPagination, useGridSelection, useGridSort };