# vTable

An advanced data table component for the Ionic Vue framework, offering powerful features for data display, manipulation, and interaction.

<p>
  <a href="https://sonarcloud.io/summary/new_code?id=uniquedj95_vtable"><img src="https://sonarcloud.io/api/project_badges/measure?project=uniquedj95_vtable&metric=alert_status" /></a>
  <a href="https://ionicframework.com/"><img src="https://badgen.net/badge/Ionic/5.x/blue" alt="Ionic"></a>
  <a href="https://vuejs.org/"><img src="https://badgen.net/badge/Vue/3.x/cyan" alt="Vue"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://badgen.net/badge/Typescript/4.x/yellow" alt="TS"></a>
  <a href="https://www.npmjs.com/package/@uniquedj95/vtable"><img src="https://img.shields.io/npm/dm/@uniquedj95/vtable.svg" alt="Downloads"></a>
</p>

![Example Table](screenshort.png 'Example Table')

---

## Installation

Install via npm or yarn:

```bash
npm install @uniquedj95/vtable
# OR
yarn add @uniquedj95/vtable
```

---

## Usage

### Register vTable Globally

```typescript
// src/main.ts
import { VTable } from '@uniquedj95/vtable';
// Import datatable CSS
import '@uniquedj95/vtable/dist/lib/datatable.css';

const app = createApp(App).use(IonicVue).use(VTable).use(router);

router.isReady().then(() => {
  app.mount('#app');
});
```

```html
<!-- Example.vue -->
<template>
  <data-table :rows="rows" :columns="columns"></data-table>
</template>
```

### Register vTable Locally

```html
<script lang="ts">
  import { DataTable } from '@uniquedj95/vtable';
  import { defineComponent } from 'vue';

  export default defineComponent({
    data: () => ({
      rows: [],
      columns: [],
    }),
    components: {
      DataTable,
    },
  });
</script>

<template>
  <data-table :rows="rows" :columns="columns"></data-table>
</template>
```

> **Note:** You must manually import styles from `@uniquedj95/vtable/dist/lib/datatable.css`.

---

## API Reference

### 1. Props

| Prop Name        | Default Value | Description                                                           |
| ---------------- | ------------- | --------------------------------------------------------------------- |
| rows             | [ ]           | List of data objects mapped into table rows                           |
| asyncRows        | undefined     | A promise function that returns a list of data                        |
| columns          | [ ]           | List of table column definitions                                      |
| actionButtons    | [ ]           | List of buttons for global table actions                              |
| rowActionButtons | [ ]           | List of buttons for actions affecting specific rows                   |
| customFilters    | [ ]           | List of custom filters affecting the data source                      |
| color            | undefined     | Color theme for the datatable. Accepted: `primary`, `secondary`, etc. |
| config           | undefined     | Configuration object affecting datatable behavior                     |

#### 1.1 Table Column

A table column is defined with the following properties:

| Property Name     | Required | Description                                                         |
| ----------------- | -------- | ------------------------------------------------------------------- | ------ | ------------------------------ |
| label             | Yes      | The column heading text (e.g. `First Name`)                         |
| path              | Yes      | The key used to map row data to this column (e.g. `first_name`)     |
| exportable        | No       | If true, values in this column can be exported (default: `true`)    |
| initialSort       | No       | If true, this column is used for initial sorting (default: `false`) |
| sortable          | No       | If true, this column can be sorted (default: `true`)                |
| initialSortOrder  | No       | Initial sort order: `"asc"                                          | "desc" | "none"`(requires`initialSort`) |
| sortCaseSensitive | No       | If true, sorting is case sensitive (default: `false`)               |
| drillable         | No       | If true, column data can be drilled (default: `false`)              |
| preSort           | No       | Function to process values before sorting                           |
| formatter         | No       | Function to format values for display                               |

#### 1.2 Action Button

Action buttons are displayed above the table and affect the entire table. Each action button has the following properties:

| Property Name | Required | Type     | Description                                                               |
| ------------- | -------- | -------- | ------------------------------------------------------------------------- | --- |
| label         | Yes      | String   | Button label (e.g. `Submit`)                                              |
| icon          | No       | ionicons | Icon displayed with the label, separated by `                             | `   |
| color         | No       | String   | Button color (default: `primary`)                                         |
| action        | Yes      | Function | Click handler. Receives `activeRows`, `allRows`, `filters`, and `columns` |

#### 1.3 Row Action Button

Row action buttons are attached to each row for row-specific actions. Each button has the following properties:

| Property Name | Required | Type     | Description                                                              |
| ------------- | -------- | -------- | ------------------------------------------------------------------------ |
| label         | No       | String   | Button label. If both label and icon are missing, defaults to `"Button"` |
| icon          | No       | ionicon  | Icon string. If both label and icon are defined, icon is used            |
| color         | No       | String   | Button color (default: `primary`)                                        |
| default       | No       | Boolean  | If true, button listens to whole row clicks (default: `false`)           |
| condition     | No       | Function | Returns boolean to show/hide the button (default: `() => true`)          |
| action        | Yes      | Function | Click handler. Receives row data and its index                           |

#### 1.4 Custom Filter

Custom filters are used when fetching data from the source/API. Each filter has the following properties:

| Property Name | Required | Type     | Description                                        |
| ------------- | -------- | -------- | -------------------------------------------------- | -------- | ------ | -------- | ------------ |
| id            | Yes      | String   | Unique identifier for the filter                   |
| label         | No       | String   | Filter input label                                 |
| value         | No       | any      | Default value for the filter                       |
| gridSize      | No       | Number   | Column grid size (1-12)                            |
| type          | Yes      | String   | Filter input type: `"text"                         | "number" | "date" | "select" | "dateRange"` |
| options       | No       | Array    | Options for select input filters                   |
| placeholder   | No       | String   | Placeholder text when no value is set              |
| required      | No       | Boolean  | If true, filter must be set before emitting events |
| multiple      | No       | Boolean  | For `select` type: allows multiple selection       |
| onUpdate      | No       | Function | Callback when filter value changes                 |
| slotName      | No       | String   | Used for defining named slots for advanced filters |

##### 1.4.1 Filter Option

A filter option object has the following properties:

| Property Name | Required | Type          | Description                                         |
| ------------- | -------- | ------------- | --------------------------------------------------- |
| label         | Yes      | String        | Option label                                        |
| value         | Yes      | String/Number | Option value                                        |
| isChecked     | No       | Boolean       | If true, option is selected (for checkboxes/radios) |
| other         | No       | any           | Any additional data                                 |

#### 1.5 Table Config

General configuration options for the datatable:

| Property Name    | Required | Type    | Default | Description                                                                                                     |
| ---------------- | -------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| showSubmitButton | No       | Boolean | false   | Show/hide submit button for custom filters. If enabled, filter changes are not emitted until submit is pressed. |
| showSearchField  | No       | Boolean | true    | Show/hide the search input field. If disabled, search is hidden even if data is available.                      |
| showIndices      | No       | Boolean | false   | Show/hide index numbers column                                                                                  |

---

### 2. Events

The data table emits the following events:

| Event Name   | Description                                                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| customFilter | Emitted when the submit button is clicked and all required filters are set. If `showSubmitButton` is false, emitted whenever a filter changes. |
| drilldown    | Emitted when a drillable cell is clicked                                                                                                       |

---

## Examples

### Basic Usage

```vue
<template>
  <data-table :rows="rows" :columns="columns" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const rows = ref([
  { id: 1, name: 'Alice', age: 30 },
  { id: 2, name: 'Bob', age: 25 },
]);

const columns = ref([
  { label: 'ID', path: 'id' },
  { label: 'Name', path: 'name' },
  { label: 'Age', path: 'age', sortable: true },
]);
</script>
```

### With Action Buttons

```vue
<template>
  <data-table :rows="rows" :columns="columns" :actionButtons="actionButtons" />
</template>

<script setup lang="ts">
const actionButtons = [
  {
    label: 'Export',
    icon: 'download-outline',
    color: 'secondary',
    action: (activeRows, allRows) => {
      // Export logic here
      alert(`Exporting ${activeRows.length} rows`);
    },
  },
];
</script>
```

### With Row Action Buttons

```vue
<template>
  <data-table :rows="rows" :columns="columns" :rowActionButtons="rowButtons" />
</template>

<script setup lang="ts">
const rowButtons = [
  {
    icon: 'trash-outline',
    color: 'danger',
    action: (row, index) => {
      // Delete logic here
      alert(`Delete row ${index + 1}`);
    },
  },
];
</script>
```

### With Custom Filters

```vue
<template>
  <data-table
    :rows="rows"
    :columns="columns"
    :customFilters="filters"
    @customFilter="onFilter"
  />
</template>

<script setup lang="ts">
const filters = [
  {
    id: 'name',
    label: 'Name',
    type: 'text',
    placeholder: 'Search by name',
  },
];

function onFilter(filterValues) {
  // Handle filter changes
  console.log(filterValues);
}
</script>
```

---

## Development

This project uses modern development tools to ensure code quality and consistency:

### 🛠️ Development Setup

```bash
# Install dependencies
npm install

# Run tests
npm test

# Watch mode for development
npm run test:watch

# Build the project
npm run build
```

### 📋 Code Quality Tools

- **ESLint**: Linting and code quality checks
- **Prettier**: Code formatting
- **Husky**: Git hooks automation
- **Commitlint**: Conventional commit message validation
- **Lint-staged**: Run linters on staged files only

### 🎯 Available Scripts

```bash
# Linting
npm run lint          # Lint and auto-fix issues
npm run lint:check    # Check for lint issues without fixing

# Formatting
npm run format        # Format all files with Prettier
npm run format:check  # Check if files are formatted correctly

# Testing
npm test              # Run all tests
npm run test:watch    # Run tests in watch mode
npm run test:ui       # Run tests with UI

# Building
npm run build         # Build the project for production
```

### 📝 Commit Message Format

This project follows [Conventional Commits](https://conventionalcommits.org/). Use the following format:

```
type(scope): description

# Examples:
feat: add new filtering feature
fix: resolve pagination bug
docs: update API documentation
refactor: improve table rendering performance
```

For more details on development standards, see [CODE_STANDARDS.md](CODE_STANDARDS.md).

---

## Contribution

Contributions are welcome! Please open issues or submit pull requests for improvements, bug fixes, or new features.

---

## License

[MIT](LICENSE)