@znap/components-vue2 1.0.9 → 1.0.11

package/README.md

@@ -1,257 +1,359 @@
-# @znap/components-vue2
 
-### ⚡ Inicio Rapido
 
-Utilizando [pnpm](https://pnpm.io/)
-```bash
-pnpm install @znap/components-vue2
-```
+## Utilização da Classe Auxiliar **CrudViewConfigs**
 
-Utilizando [npm](https://npmjs.com/)
-```bash
-npm install @znap/components-vue2
-```
+O intuito dessa classe é fornecer ao desenvolvedor uma interface padronizada de criação de telas, tornando o processo padronizado e de fácil aprendizado.
 
-No arquivo **main.js** do Vue.
+A classe retorna métodos e um objeto padrão de estado para ser utilizado para manipular o componente **ZnapBaseCrudView** por meio dos getters **viewConfigs** e **viewMethods**, além disso, possui diversos métodos/interfaces para o desenvolvedor adicionar elementos na tela de maneira padronizada evitando refazer a roda toda vez que for construir uma nova tela.
 
-```javascript
-import Vue from "vue";
-import * as ZnapComponents from '@znap/components-vue2';
+### Objeto de Estado (viewConfigs):
+  ```typescript
+  type AvalibleFilterComponents = "v-autocomplete" | "v-checkbox" | "date-picker"
+  type AvalibleFormOptionHooks = "afterChange" | "beforeChange"
+  type AvalibleFilterOptionHooks = "afterChange"
+  type AvalibleFormHooks = "beforeSetItem" | "afterSetItem"
+  type Endpoint = [string, {[key: string]: any}]
+  type ComponentProps = {
+    required?: boolean
+    multiple?: boolean
+    label: string
+    range?: string
+    [key: string] : any
+  }
 
-// -- Configuraçoes do Hands on Table (Opicional)
-import { registerAllModules } from "handsontable/registry";
-import { registerLanguageDictionary, ptBR } from "handsontable/i18n";
-import numbro from "numbro";
-import numbroptBR from "numbro/dist/languages/pt-BR.min.js";
+  interface FiltersInterface {
+    column: string
+    filterComponent: AvalibleFilterComponents
+    itemsArray: any[]
+    initialValue: any
+    endpoint: Endpoint
+    componentProps: ComponentProps
+    hooks: AvalibleFilterOptionHooks
+    dependsOn: string
+    ignoreOnFetchFunction: boolean
+  }
 
-numbro.registerLanguage(numbroptBR);
-numbro.setLanguage("pt-BR");
-registerAllModules();
-registerLanguageDictionary(ptBR);
-// -- Fim
+  interface TableOptionsInterface {
+    column: string
+    itemsArray: any[]
+    endpoint: Endpoint
+    formatter: (value: any) => any
+    filterFunction: () => any[]
+    ignoreOnFetchFunction: boolean
+  }
 
-Vue.use(ZnapComponents.plugin, {
-  licenseKey: HOT_TABLE_LICENSE_KEY // CHAVE DE UTILIZAÇAO DO HANDS ON TABLE
-})
-```
+  interface FormOptionsInterface {
+    column: string
+    itemsArray: any[]
+    dependsOn: any
+    endpoint: Endpoint
+    hooks: AvalibleFormOptionHooks
+    ignoreOnFetchFunction: boolean
+  }
 
-### Estrutura de importaçao da lib:
+  const viewConfigs = {
+      tableName: string,
+      tableIcon: string,
+      headers: [],
+      columns: [],
+      apiData: any[],
+      useServerSidePagination: boolean,
+      useServerSideSearch: boolean,
+      paginationSettings: {
+        page: number,
+        itemsPerPage: number,
+        itemsPerPageOptions: number[],
+        serverItemsLength: number | null
+      },
+      searchColums: string[],
+      primaryKey: string,
+      loading: boolean,
+      rowsChanged: Set<number>,
+      filters: {
+        primary: FiltersInterface[]
+        secondary: FiltersInterface[]
+        search: ''
+      },
+      currentFilters: {
+        primary: any[]
+        secondary: any[]
+        search: ''
+      },
+      tableOptions: TableOptionsInterface[],
+      formSettings: {
+        baseModel: {
+          [string]: any
+        },
+        formOptions: FormOptionsInterface[],
+        hooks: {
+          beforeSetItem: (item: any) => any | Promise<any>,
+          afterSetItem: (item: any) => any | Promise<any>,
+        },
+        loading: false,
+      },
+      endpoint: Endpoint,
+      hasFetch: boolean,
+  }
+  ```
 
-```javascript
-import * as ZnapComponents from '@znap/components-vue2';
+  - **tableName**: O texto que será exibido como título da página.
 
-// ZnapComponents.plugin: Plugin de instalaçao global de todos com componentes para utilizaçao sem importaçao no template vue.
+  - **tableIcon**: O ícone que será exibido ao lado do título da página.
 
-// ZnapComponents.components: Retorna todos os componentes exportados pela lib
+  - **headers**: Array de headers que é retornado do back-end.
+  
+  - **columns**: Array de colunas retornado do back-end.
+  
+  - **apiData**: Array de dados que será exibido na tabela.
 
-// ZnapComponents.utils: Retorna todas as funçoes uteis exportadas pela lib
-```
+  - **endpoint**: Tupla/Array de 2 posições onde a primeira é a URL do endpoint principal da página e a segunda os parâmetros que serão passados para esse endpoint.
+  
+  - **hasFetch**: Booleano que indica que já ocorreu o fetch de dados da página.
+  
+  - **useServerSidePagination**: Booleano para controlar a paginação do lado servidor.
 
-### Utilizaçao do ZnapBaseCrudView
-
-```javascript
-<template>
-  <ZnapBaseCrudView
-    v-if="viewSettings"
-    ref="baseCrudViewRef"
-    v-bind="viewSettings"
-    :onReload="onReload"
-    :onExport="onExportFile"
-    :onImport="onImportFile"
-    :onSave="onSave"
-    :onDelete="onDelete"
-    @update:rows-changed="updateRowsChanged"
-    @update:row="updateRow"
-  >
-  <template v-slot:footer-prepend>
-    Slot para adicionar elementos do lado esquerdo dos componentes de paginaçao.
-  </template>
-  </ZnapBaseCrudView>
-</template>
-
-<script>
-import Vue from "vue";
-import { utils as ZnapUtils } from "@znap/components-vue2";
-
-export default {
-  data: () => ({
-    viewSettings: null,
-    viewMethods: null,
-  }),
-
-  async created() {
-    const { CrudViewConfigs } = ZnapUtils; // Importar a classe CrudViewConfigs da utils para gerar o template de dados da tela
-
-    const crudViewConfigs = new CrudViewConfigs({
-      viewTitle: "Titulo da pagina",
-      viewIcon: "icone_da_pagina",
-      primaryKey: "chave_primaria_da_tela",
-      endpoint: CrudViewConfigs.generateEndpoint(
-        "URL", {} // parametros
-      ),
-      useServerSidePagination?: false, // Habilita a paginaçao do lado do servidor  por padrao vem desabilitado. (Se habilitado a busca tambem passa a acontecer do lado do servidor)
-      useServerSideSearch?: false, // Habilita busca do lado do servidor por padrao vem desabilitado
-    });
-
-    crudViewConfigs
-      .addPrimaryFilter({
-        column: "coluna_que_ira_buscar", 
-        filterComponent: "v-autocomplete", // componentes disponiveis: v-autocomplete, v-checkbox, date-picker
-        itemsArray?: [] // Array de dados iniciais
-        initialValue?: null // Valor inicial
-        endpoint?: CrudViewConfigs.generateEndpoint(
-         "URL", {} // parametros
-        ),
-        componentProps: {
-          label: "Grupo empresarial",
-          clearable?: true,
-          required?: true // Se o valor for true, ele devera ser preenchido e se caso nao for preenchido ira exibir mensagem na tela
-          multiple?: false // Se for um v-autocomplete permite selecionar varios items
-          range?: false // Se for um date-picker permite selecionar um range de data.
-        }, // Props que sera passada para o componente
-         dependsOn?: '' // Filtro primario que possui dependencia
-         hooks?: {
-          afterChange: () => {
-            // Hook que sera disparado apos a mudança do valor
-
-            // * Pode ser utilizado para alterar os dados de outros filtros, ou entao realizar chamadas asincronas para atualizar o array de dados.
-          }
-        }
-      })
-
-    crudViewConfigs
-      .addSecondaryFilter({
-        column: "coluna_que_ira_buscar",
-        filterComponent: "v-autocomplete", // componentes disponiveis: v-autocomplete, v-checkbox, date-picker
-        itemsArray?: [] // Array de dados iniciais
-        initialValue?: null // Valor inicial
-        endpoint?: CrudViewConfigs.generateEndpoint(
-         "URL", {} // parametros
-        ),
-        componentProps: {
-          label: "Empresa",
-          clearable?: true,
-          multiple?: false // Se for um v-autocomplete permite selecionar varios items
-          range?: false // Se for um date-picker permite selecionar um range de data.
-        }, // Props que sera passada para o componente
-        dependsOn?: '' // Filtro secundario que possui dependencia
-        hooks?: {
-          afterChange: () => {
-            // Hook que sera disparado apos a mudança do valor
-            
-            // * Pode ser utilizado para alterar os dados de outros filtros, ou entao realizar chamadas asincronas para atualizar o array de dados.
-          }
-        }
-      })
-     
-    crudViewConfigs
-      .addTableOption({
-        column: "chave_que_recebera_as_options",
-        itemsArray?: [] // Array com dados iniciais
-        endpoint?: CrudViewConfigs.generateEndpoint(
-         "URL", {
-          // parametros
-         }
-        ),
-        formatter?: (value) => {
-          // Logica para formatar o dado quando for exibir na tabela, sem alterar o dado original
-        }
-        filterFunction?: () => {
-          // Logica parar filtrar os dados que serao exibidos, se for passado uma filterFunction o array de items sera ignorado e o retorno sera o retorno da filterFunction.
-
-          // Deve sempre retornar um array
-        }
-      })
-    
-
-    crudViewConfigs
-      .addFormOption({
-        column: "chave_que_recebera_as_options",
-        dependsOn?: 'chave_que_dependa_que_tenha_valor'
-        itemsArray?: [] // Array de itens iniciais
-        endpoint?: CrudViewConfigs.generateEndpoint(
-         "URL", {} // parametros
-        ),
-        hooks?: {
-          afterChange: (item) =>{
-            // Logica que ira disparar apos o valor ser alterado
-
-            // * Pode ser utilizado para alterar os dados ou entao realizar chamadas asincronas para atualizar o array de dados.
-          }
-          beforeChange: (item) => {
-            // Logica que ira disparar antes do valor ser alterado
-            
-            // * Pode ser utilizado para alterar os dados ou entao realizar chamadas asincronas para atualizar o array de dados.
-          }
-        }
-      })
-    
-    crudViewConfigs.setFormModel({
-      // Modelo inicial do formulario
-    });
-
-    this.viewSettings = crudViewConfigs.viewConfigs; // Retorna o objeto de configuraçoes da classe (Se tornara o state do componente)
-    this.viewMethods = crudViewConfigs.viewMethods; // Retorna os metodos pre prontos disponiveis da classe.
+  - **useServerSideSearch**: Booleano para controlar a busca do lado servidor. **Se 
+  useServerSidePagination for True, essa opção deve ser True também.**
+
+  - **paginationSettings**: Objeto de configuração de paginação.
+      - **page**: Pagina atual.
+      - **itemsPerPage**: Quantidade de itens por pagina.
+      - **serverItemsLength**: Quantidade total de itens para paginar **Se estiver utilizando paginação do lado servidor, essa informação deve ser atribuída, caso contrario, a paginação irá quebrar.**
+      - **itemsPerPageOptions**: Array com as opções de itemsPerPage: Para ter a opçao **Todos** o valor **-1 deve ser atribuído no Array**.
 
+   - **searchColums**: Array com as colunas que serão utilizadas na busca por texto.
    
-    // Pode usar os metodos das classe CrudViewConfigs ou entao criar os proprios de acordo com a necessidade.
-    await Promise.all([
-      this.viewMethods.fetchFiltersData(this.viewSettings.filters, this.$http),
-      this.viewMethods.fetchTableOptionsData(
-        this.viewSettings.tableOptions,
-        this.$http
-      ),
-      this.viewMethods.fetchFormOptionsData(
-        this.viewSettings.formSettings.formOptions,
-        this.$http
-      ),
-    ]);
-
-    this.fetchData()
-  },
-  methods: {
-    updateRowsChanged() {
-       this.viewSettings.rowsChanged = new Set(this.viewSettings.rowsChanged); // Importante para o Vue detectar que o rowsChanged alterou e exibir o elemento em destaque na tabela.
-    }
-    updateRow() {
-      this.$set(this.viewSettings.apiData, rowIndex, data); // Importante para o vue detectar que teve alteraçao no elemento da tabela.
-    }
-    async onReload() {
-      // Logica de como sera tratado o evento de reload.
-    }
-    async onExportFile() {
-       // Logica de como sera tratado o evento de exportaçao de arquivo.
-    }
-    async onImportFile(
-      event // evento contendo o elemento do input de arquivo
-      ) {
-      // Logica de como sera tratado o evento de importaçao de arquivo.
-    }
-    async onSave({
-    reload = true, // variavel retornada do comoponente para verificar se deve ou nao realizar o reload (Fica a cargo do desenvolvedor)
-    itemData = null  // Se for um item proveniente da modal (Criaçao/Ediçao) os dados virão aqui
-    }) {
-      // Logica de como sera tratado o evento de salvamento de registro(s)
-    }
-    async onDelete(
-      rows // Array com as linhas que devem ser excluidas
-    ) {
-      // Logica de como sera tratado o evento de exclusao de registro(s)
-    }
-    async fetchData() {
-      // Logica de busca de dados principais
-    }
-  }
+   - **primaryKey**: Chave primária da tela.
+   
+   - **loading**: Booleano que controla o estado de loading da tela.
+   
+   - **rowsChanged**: Set contendo os **índices físicos** das linhas que foram alterados.
+   
+   - **filters**: Objeto de filtros.
+      - **primary**: Array contendo todos os filtros primários
+      - **secondary**: Array contendo todos os filtros secundários
+      - **search**: String que será utilizada em busca por texto.
+
+  - **currentFilters**: Objeto contendo os filtros que realmente estão selecionados após o fetch de dados.
+      - **primary**: Array contendo os valores selecionados nos filtros primários.
+      - **secondary**: Array contendo os valores selecionados nos filtros secundários.
+      - **search**: String contendo o filtro de texto selecionado.
+
+  - **tableOptions**: Array contendo as opções das colunas da tabela.
+
+  - **formSettings**: Objeto de configurações do formulário:
+      - **baseModel**: Objeto contendo a estrutura inicial do objeto do item a ser criado/editado.
+      - **formOptions**: Array contendo as opçoes dos campos do formulário.
+      - **hooks**: Objeto contendo as funçoes de hooks do formulário:
+        - **beforeSetItem**: Função a ser executada antes do item ser atribuído ao formulário.
+        - **afterSetItem**: Função a ser executada após o item ser atribuído ao formulário.
+
+### Objeto de métodos (viewMethods)
+```typescript
+type KeysToValidate = 'search' | 'primary' | 'secondary'
+type FetcherReturn = {data: {rows: any[]}, [key: string]: any}
+type HttpFetcher = {
+  post: (url: string, params: {[key: string] : any}) => Promise<FetcherReturn>,
+  get: (url: string) => Promise<FetcherReturn>,
+  delete: (url: string) => Promise<FetcherReturn>,
 }
-</script>
 
+const viewMethods = {
+  getFilters: (filters, searchColums) => void,
+  fetchTableOptionsData: (tableOptions, httpFetcher: HttpFetcher) => void,
+  fetchFormOptionsData: (formOptions, httpFetcher: HttpFetcher) => void,
+  fetchFiltersData: (filters, httpFetcher: HttpFetcher) => void,
+  setCurrentFilters: (filters) => void,
+  validateFiltersKeyHaveChange: (filters, currentFilters, keysToValidate: KeysToValidate[] ) => boolean,
+}
 ```
-
-
-### Utilizaçao da Classe Auxiliar **CrudViewConfigs**
-
-O intuito dessa classe é fornecer ao desenvolvedor uma interface padronizada de criaçao de telas, tornando o processo padronizado e de facil aprendizado.
-
-A classe retorna metodos e um objeto padrao de estado para ser utilizado para manipular o componente **ZnapBaseCrudView** por meio dos getters **viewConfigs** e **viewMethods**, alem disso, pussui diversos metodos/interfaces para o desenvolvedor adicionar elementos na tela de maneira padronizada evitando refazer a roda toda vez que for construir uma nova tela.
-
-
+  - **getFilters**: função responsável por retornar o array de condições de todos os filtros de maneira formatada para atribuir aos endpoints.
+    - Parâmetros:
+      - Objeto de filtros.
+      - Array de searchColums
+
+  - **fetchTableOptionsData**: função genérica responsável por realizar o fetch de todos os dados do Array de tableOptions.
+
+  - **fetchFormOptionsData**: função genérica responsável por realizar o fetch de todos os dados do Array de formOptions.
+
+  - **fetchFiltersData**: função genérica responsável por realizar o fetch de todos os dados do Array de filtros.
+
+  - **setCurrentFilters**: função que retorna os valores dos filtros selecionados.
+    - Parâmetros: 
+      - Array de filtros.
+
+  - **validateFiltersKeyHaveChange**: função para validar se os filtros selecionados na tela possuem diferença com os filtros que de fato estão selecionados.
+    - Parâmetros:
+      - Objeto de filtros.
+      - Objeto de currentFilters
+      - Array com as chaves dos filtros que deseja comparar.
+
+### Métodos de geração do Estado inicial:
+A classe possui diversos métodos para gerar o objeto inicial de estado (viewConfigs), esses métodos são interfaces padrões para facilitar e padronizar a estrutura de dados que será passada para o componente.
+
+- Métodos Estáticos:
+  - **generateEndpoint**: Retorna o Array/Tupla de endpoint.
+    ```javascript
+    CrudViewConfigs.generateEndpoint(url: string, parâmetros?: {}): [string, {}]
+    ```
+
+- Métodos da instância:
+  - **addPrimaryFilter**: Adiciona um filtro primário no array de filtros.
+      ```javascript
+      crudViewConfigs.addPrimaryFilter({
+        column: string,
+        filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
+        itemsArray?: any[],
+        initialValue?: any | null,
+        endpoint?: [string, {}],
+        componentProps: {
+          label: string,
+          required?: boolean,
+          [string]: any
+        },
+        dependsOn?: string,
+        ignoreOnFetchFunction?: boolean 
+      }): this
+      ```
+
+  - **setPrimaryFilters**: Permite atribuir de maneira manual todo o Array de filtros primários.
+    ```javascript
+    crudViewConfigs.setPrimaryFilters([
+      {
+        column: string,
+        filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
+        itemsArray?: any[],
+        initialValue?: any | null,
+        endpoint?: [string, {}],
+        componentProps: {
+          label: string,
+          required?: boolean,
+          multiple?: boolean,
+          range?: boolean,
+          [string]: any
+        },
+        dependsOn?: string,
+        ignoreOnFetchFunction?: boolean 
+      }...
+    ]): this
+    ```
+
+  - **addSecondaryFilter**: Adiciona um filtro secundário no array de filtro secundário.
+      ```javascript
+      crudViewConfigs.addSecondaryFilter({
+        column: string,
+        filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
+        itemsArray?: any[],
+        initialValue?: any | null,
+        endpoint?: [string, {}],
+        componentProps: {
+          label: string,
+          [string]: any
+        },
+        dependsOn?: string,
+        ignoreOnFetchFunction?: boolean 
+      }): this
+      ```
+
+  - **setSecondaryFilters**: Permite atribuir de maneira manual todo o Array de filtro secundário.
+    ```javascript
+    crudViewConfigs.setSecondaryFilters([
+      {
+        column: string,
+        filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
+        itemsArray?: any[],
+        initialValue?: any | null,
+        endpoint?: [string, {}],
+        componentProps: {
+          label: string,
+          [string]: any
+        },
+        dependsOn?: string,
+        ignoreOnFetchFunction?: boolean 
+      }...
+    ]) : this
+    ```
+
+  - **addTableOption**: Adiciona uma opção referente a uma coluna na tabela principal no Array de tableOptions.
+      ```javascript
+      crudViewConfigs.addTableOption({
+        column: string,
+        itemsArray?: any[],
+        endpoint?: [string, {}],
+        formatter?: (value: any) => any
+        filterFunction?: () => any[]
+        ignoreOnFetchFunction?: boolean 
+      }): this
+      ```
+
+  - **setTableOptions**: Permite atribuir de maneira manual todo o Array de tableOptions.
+    ```javascript
+    crudViewConfigs.setTableOptions([
+      {
+        column: string,
+        itemsArray?: any[],
+        endpoint?: [string, {}],
+        formatter?: (value: any) => any
+        filterFunction?: () => any[]
+        ignoreOnFetchFunction?: boolean 
+      }...
+    ]): this
+    ```
+
+  - **setFormModel**: Adiciona o modelo base de dados do formulário.
+    ```javascript
+    crudViewConfigs.setFormModel(any{}): this
+    ```
+
+   - **addFormOption**: Adiciona uma opção referente a uma coluna do formulario no Array de formOptions.
+      ```javascript
+      crudViewConfigs.addFormOption({
+        column: string,
+        itemsArray?: any[],
+        dependsOn?: string,
+        endpoint?: [string, {}],
+        ignoreOnFetchFunction?: boolean,
+        hooks?: {
+          afterChange?: (item: any) => any
+          beforeChange?: (item: any) => any
+        } 
+      }): this
+      ```
+
+    - **setFormOptions**: Permite atribuir de maneira manual todo o Array de formOptions.
+      ```javascript
+      crudViewConfigs.setFormOptions([{
+          column: string,
+          itemsArray?: any[],
+          dependsOn?: string,
+          endpoint?: [string, {}],
+          ignoreOnFetchFunction?: boolean,
+          hooks?: {
+            afterChange?: (item) =>  any,
+            beforeChange?: (item) => any
+          }}]): this
+      ```
+
+     - **setFormHooks**: Permite atribuir de maneira manual todos os hooks do formulário.
+        ```javascript
+        crudViewConfigs.setFormHooks({
+          beforeSetItem?: (item: any) => any | Promise<any>,
+          afterSetItem?: (item: any) => any | Promise<any>
+        }): this
+        ```
+
+     - **addFormHook**: Permite atribuir de maneira manual todos os hooks do formulário.
+        ```javascript
+        crudViewConfigs.addFormHook(key: 'beforeSetItem' | 'afterSetItem', (item: any) => any | Promise<any> ): this
+        ```
+
+    - **setPaginationSettings**: Permite atribuir de maneira manual o objeto paginationSettings.
+        ```javascript
+        crudViewConfigs.setPaginationSettings({
+          page: number,
+          itemsPerPage: number,
+          itemsPerPageOption?: number[],
+          serverItemsLength?: number | null,
+        }): this
+        ```
+