@xosen/vuetify-grid 0.0.1

package/README.md

@@ -0,0 +1,289 @@
+# @xosen/vuetify-grid
+
+Advanced data grid and list components for Vuetify 3 with built-in CRUD operations, actions, pagination, and search.
+
+## Installation
+
+```bash
+npm install @xosen/vuetify-grid
+# or
+pnpm add @xosen/vuetify-grid
+# or
+yarn add @xosen/vuetify-grid
+```
+
+## Usage
+
+### Import Components and Styles
+
+```typescript
+import { XGrid, XList, XTree, SchemaList } from '@xosen/vuetify-grid';
+import '@xosen/vuetify-grid/dist/style.css';
+```
+
+### XGrid - Data Table Component
+
+A powerful data table component with server-side or client-side data loading, sorting, filtering, and actions.
+
+```vue
+<template>
+  <XGrid
+    title="Users"
+    :headers="headers"
+    :on-load="loadUsers"
+    :row-actions="rowActions"
+    :toolbar-actions="toolbarActions"
+    searchable
+    refreshable
+  />
+</template>
+
+<script setup lang="ts">
+import { XGrid } from '@xosen/vuetify-grid';
+import type { GridColumn, ActionsConfig } from '@xosen/vuetify-grid';
+
+const headers: GridColumn[] = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'email', label: 'Email', sortable: true },
+  { key: 'role', label: 'Role' },
+];
+
+async function loadUsers(params: { page: number; limit: number; search?: string }) {
+  const response = await fetch(`/api/users?page=${params.page}&limit=${params.limit}`);
+  const data = await response.json();
+  return { data: data.users, meta: { total: data.total } };
+}
+
+const rowActions: ActionsConfig = {
+  edit: {
+    icon: 'mdi-pencil',
+    handler: (user) => console.log('Edit', user),
+  },
+  delete: {
+    icon: 'mdi-delete',
+    color: 'error',
+    handler: async (user) => {
+      await fetch(`/api/users/${user.id}`, { method: 'DELETE' });
+    },
+  },
+};
+
+const toolbarActions: ActionsConfig = {
+  create: {
+    text: 'New User',
+    icon: 'mdi-plus',
+    handler: () => console.log('Create new user'),
+  },
+};
+</script>
+```
+
+### XList - List View Component
+
+A flexible list component using Vuetify's VDataIterator with support for custom item rendering.
+
+```vue
+<template>
+  <XList
+    title="Products"
+    :on-load="loadProducts"
+    :row-actions="rowActions"
+    searchable
+  >
+    <template #item="{ item }">
+      <v-list-item>
+        <v-list-item-title>{{ item.name }}</v-list-item-title>
+        <v-list-item-subtitle>{{ item.price }}</v-list-item-subtitle>
+      </v-list-item>
+    </template>
+  </XList>
+</template>
+```
+
+### XTree - Tree View Component
+
+A tree component with hierarchical data display and actions.
+
+```vue
+<template>
+  <XTree
+    title="File Explorer"
+    :items="fileTree"
+    :row-actions="treeActions"
+    item-title="name"
+    item-value="id"
+    item-children="children"
+  />
+</template>
+```
+
+### SchemaList - Schema-based List
+
+Create lists using a declarative schema without writing component templates.
+
+```typescript
+import { SchemaList, type ListSchema } from '@xosen/vuetify-grid';
+
+const schema: ListSchema = {
+  title: 'Products',
+  searchable: true,
+  refreshable: true,
+  itemsPerPage: 25,
+  onLoad: async (params) => {
+    const response = await fetch(`/api/products?${new URLSearchParams(params as any)}`);
+    const data = await response.json();
+    return { data: data.products, meta: { total: data.total } };
+  },
+  rowActions: {
+    edit: { icon: 'mdi-pencil', handler: (item) => console.log('Edit', item) },
+    delete: { icon: 'mdi-delete', color: 'error', handler: deleteProduct },
+  },
+  toolbarActions: {
+    create: { text: 'New Product', icon: 'mdi-plus', handler: () => console.log('Create') },
+  },
+  noDataText: 'No products found',
+};
+```
+
+## Features
+
+### Grid Features
+- ✅ Server-side and client-side data loading
+- ✅ Built-in pagination
+- ✅ Search functionality
+- ✅ Sorting support
+- ✅ Row and toolbar actions
+- ✅ Loading states
+- ✅ Customizable columns
+- ✅ Responsive design
+
+### Action System
+- Icon-only or button actions
+- Async action handlers with loading states
+- Conditional visibility and disabled states
+- Menu actions for overflow
+- Success/error handling
+
+### CRUD Operations
+- Built-in `useCrudGrid` composable
+- Automatic data loading and reloading
+- Filter support
+- Debounced search
+- Required filters validation
+
+## API Reference
+
+### XGrid Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | - | Grid title |
+| `headers` | `GridColumn[]` | - | Column definitions |
+| `items` | `any[]` | - | Items for client-side mode |
+| `onLoad` | `Function` | - | Server-side data loader |
+| `rowActions` | `ActionsConfig` | - | Row-level actions |
+| `toolbarActions` | `ActionsConfig` | - | Toolbar actions |
+| `searchable` | `boolean` | `false` | Enable search |
+| `refreshable` | `boolean` | `false` | Enable refresh button |
+| `itemsPerPage` | `number` | `10` | Items per page |
+| `sortable` | `boolean` | `true` | Enable sorting |
+| `hover` | `boolean` | `true` | Highlight on hover |
+
+### GridColumn Interface
+
+```typescript
+interface GridColumn {
+  key: string;
+  label: string;
+  sortable?: boolean;
+  width?: string | number;
+  align?: 'start' | 'center' | 'end';
+}
+```
+
+### ActionConfig Interface
+
+```typescript
+interface ActionConfig {
+  text?: string | ((item?: any) => string);
+  icon?: string;
+  color?: string;
+  disabled?: boolean | ((item?: any) => boolean);
+  visible?: boolean | ((item?: any) => boolean);
+  handler?: (item?: any) => Promise<any> | any;
+  loading?: boolean;
+}
+```
+
+## Composables
+
+### useCrudGrid
+
+Manages CRUD operations with pagination, search, and filtering.
+
+```typescript
+const {
+  loading,
+  page,
+  limit,
+  items,
+  total,
+  reload,
+  loadData,
+} = useCrudGrid({
+  onLoad: async (params) => {
+    // Fetch data
+    return { data: [], meta: { total: 0 } };
+  },
+});
+```
+
+### useActions
+
+Manages action states and execution.
+
+```typescript
+const { handleActionClick, isActionVisible, isActionDisabled } = useActions({
+  onError: (error) => console.error(error),
+});
+```
+
+## Styling
+
+The package includes pre-built CSS. Import it in your main file:
+
+```typescript
+import '@xosen/vuetify-grid/dist/style.css';
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  GridColumn,
+  ListSchema,
+  ActionConfig,
+  ActionsConfig,
+  CrudGridOptions,
+  LoadParams,
+} from '@xosen/vuetify-grid';
+```
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Type check
+pnpm type-check
+
+# Clean build artifacts
+pnpm clean
+```
+
+## License
+
+MIT