@sankhyalabs/core 2.3.6 → 2.4.0

package/src/dataunit/loading/LoadDataRequest.ts

@@ -1,10 +1,20 @@
 import { QuickFilter } from "../DataUnit.js";
 import { Filter, Sort } from "../metadata/UnitMetadata.js";
 
+/** Atributos enviados na requisição de carregamento dos registros */
 export interface LoadDataRequest {
+    /** Indice inicial dos registros que será retornado */
     offset?: number;
+    
+    /** Quantidade de registros que será retornado */
     limit?: number;
+    
+    /** Filtro rápido */
     quickFilter?: QuickFilter;
+    
+    /** Filtros */
     filters?: Array<Filter>;
+    
+    /** Ordenação dos resultados */
     sort?: Array<Sort>;
 }

package/src/dataunit/loading/LoadDataResponse.ts

@@ -1,7 +1,11 @@
 import { Record } from "../DataUnit.js";
 import { PaginationInfo } from "./PaginationInfo.js";
 
+/** Retorno dos registros da requisição de carregamento de dados */
 export interface LoadDataResponse {
+    /** Registros retornados na requisição */
     records: Array<Record>;
+
+    /** Informações da paginação */
     paginationInfo?: PaginationInfo;
 }

package/src/dataunit/loading/PaginationInfo.ts

@@ -1,8 +1,18 @@
-
+/** Informações da paginação retornada na requisição de carregamento de registros */
 export interface PaginationInfo {
+
+    /** Página atual */
     currentPage: number;
+
+    /** Indice do primeiro registro na página */
     firstRecord: number;
+    
+    /** Indice do último registro na página */
     lastRecord: number;
+    
+    /** Quantidade total de registros */
     total: number;
+
+    /** Se ainda existem mais registros além dos exibidos na página */
     hasMore: boolean;
 }

package/src/dataunit/metadata/DataType.ts

@@ -1,5 +1,7 @@
 import DateUtils from "../../utils/DateUtils.js";
 
+/* `DataType` Tipos de dados válidos para os valores dos campos no dataUnit */
+
 export enum DataType {
     NUMBER = "NUMBER",
     DATE = "DATE",
@@ -8,6 +10,24 @@ export enum DataType {
     OBJECT = "OBJECT"
 }
 
+/**
+ * Converte o valor para outro tipo.
+ * 
+ * Tipos aceitos:
+ * 
+ * NUMBER = "NUMBER",
+ * DATE = "DATE",
+ * TEXT = "TEXT",
+ * BOOLEAN = "BOOLEAN",
+ * OBJECT = "OBJECT"
+ * 
+ * @param dataType - Tipo que o valor será convertido.
+ * @param value - Valor a ser convertido.
+ * @returns - Informação convertida para o tipo informado.
+ * 
+ * @example
+ * ``` informado: DataType.NUMBER, "10" | Retorno: 10 ```
+*/
 export const convertType = (dataType: DataType, value: any): any => {
     
     if (value === undefined || value === null) {
@@ -21,7 +41,25 @@ export const convertType = (dataType: DataType, value: any): any => {
     return getConvertedValue(dataType, value);
 }
 
-export const getConvertedValue = (dataType: DataType, value: any) => {
+/**
+ * Efetua a conversão da informação de acordo com o tipo definido pelo dataType.
+ * 
+ * Tipos aceitos:
+ * 
+ * NUMBER = "NUMBER",
+ * DATE = "DATE",
+ * TEXT = "TEXT",
+ * BOOLEAN = "BOOLEAN",
+ * OBJECT = "OBJECT"
+ * 
+ * @param dataType - Tipo que o valor será convertido.
+ * @param value - Valor a ser convertido.
+ * @returns - Informação convertida para o tipo informado.
+ * 
+ * @example
+ * ``` informado: DataType.NUMBER, "10" | Retorno: 10 ```
+*/
+export const getConvertedValue = (dataType: DataType, value: any): any => {
   switch (dataType) {
     case DataType.NUMBER:
       return value === "" || isNaN(Number(value)) ? null : Number(value);
@@ -46,6 +84,14 @@ export const getConvertedValue = (dataType: DataType, value: any) => {
   }
 }
 
+/**
+ * Converte valor para texto
+ * 
+ * @param dataType - Tipo do dado para conversão
+ * @param value - Valor a ser convertido.
+ * @returns - Valor convertido em forma de texto.
+ * 
+*/
 export const toString = ( dataType: DataType|undefined, value: any): string => {
 
     if (value === undefined || value === null) {

package/src/exceptions/ErrorException.ts

@@ -1,7 +1,15 @@
+/**
+ * `ErrorException`: Exceção lançada quando ocorre um erro. 
+ */
 export default class ErrorException extends Error {
 
+    /** Titulo do erro. */
     public title: string;
+
+    /** Descrição do erro. */
     public message: string;
+    
+    /** Código do erro, indica o erro disparado pelo backend. */
     public errorCode: string;
 
     constructor(title: string, message: string, errorCode: string = "") {

package/src/exceptions/WaitingChangeException.ts

@@ -1,7 +1,12 @@
-
+/**
+ * `WaitingChangeException`: Exceção lançada quando um campo está pendente de finalizar a alteração antes de executar uma ação.
+ */
 export default class WaitingChangeException extends Error {
 
+    /** Titulo do erro. */
     public title: string;
+
+    /** Descrição do erro. */
     public message: string;
 
     constructor(title: string, message: string) {

package/src/exceptions/WarningException.ts

@@ -1,8 +1,15 @@
-
+/**
+ * `WarningException`: Exceção lançada quando o "erro" vindo do backend é caracterizado como warning.
+ */
 export default class WarningException extends Error {
 
+    /** Titulo do alerta. */
     public title: string;
+
+    /** Descrição do alerta. */
     public message: string;
+    
+    /** Código do alerta, indica o alerta disparado pelo backend. */
     public errorCode: string;
 
     constructor(title: string, message: string, errorCode: string = "") {

package/src/traking/ErrorTraking.ts

@@ -2,7 +2,17 @@ import ErrorException from "../exceptions/ErrorException.js";
 import WaitingChangeException from "../exceptions/WaitingChangeException.js";
 import WarningException from "../exceptions/WarningException.js";
 
+/**
+ * `ErrorTracking`: Handler para processar exceptions lançadas. 
+ */
+
 export class ErrorTracking {
+
+    /**
+     * 
+     * Inicializa o Rollbar, utilizado para rastreio de erros e análise de logs.
+     * 
+    */
     public static init(){
         const rollbar = (window as any).Rollbar;
         if(rollbar){
@@ -14,6 +24,13 @@ export class ErrorTracking {
         }
     }
 
+    /**
+     * 
+     * Retorna se o erro é uma exceção interna na aplicação.
+     * @param error - Erro que será identificado como exceção interna ou não.
+     * @returns - Verdadeiro caso seja uma exceção interna.
+     * 
+    */
     private static isInternalException(error:any):boolean{
         return (error instanceof ErrorException || error instanceof WaitingChangeException || error instanceof WarningException);
     }

package/src/ui/FloatingManager.ts

@@ -30,6 +30,13 @@ class FloatingEntry {
         this.options = opts;
     }
     
+    /**
+     * 
+     * Obtém o elemento HTML pai associado ao objeto.
+     * 
+     * @returns - Elemento HTML pai.
+     * 
+    */
     public get parent():HTMLElement|undefined{
         if(this.weakRefParent){
             return this.weakRefParent.deref();
@@ -37,6 +44,13 @@ class FloatingEntry {
         return this.strongRefParent
     }
 
+    /**
+     * 
+     * Obtém o elemento HTML de conteúdo associado ao objeto.
+     * 
+     * @returns - Elemento HTML de conteúdo associado.
+     * 
+    */
     public get content():HTMLElement|undefined{
         if(this.weakRefContent){
             return this.weakRefContent.deref();
@@ -45,6 +59,9 @@ class FloatingEntry {
     }
 }
 
+/**
+ * `FloatingManager`: Gerenciador de elementos flutuantes na tela. 
+ */
 
 export default class FloatingManager {
     public static MODAL_DEFAULT_CLASSNAME = "FloatingManager__modal";
@@ -54,6 +71,12 @@ export default class FloatingManager {
     private static initialized: boolean;
     private static entries: Array<FloatingEntry>;
 
+
+    /**
+     * 
+     * Inicializa a classe FloatingManager.
+     * 
+    */
     private static init() {
         FloatingManager.entries = [];
         document.addEventListener('mousedown', FloatingManager.handleDocumentEvent);
@@ -61,7 +84,12 @@ export default class FloatingManager {
         FloatingManager.initialized = true;
     }
 
-    private static innerClick(container: HTMLElement, node: HTMLElement) {
+    /**
+     * 
+     * Retorna se o elemento clicado possui elementos internos.
+     * 
+    */
+    private static innerClick(container: HTMLElement, node: HTMLElement): boolean {
         if (container.contains(node)) {
             return true;
         }
@@ -73,7 +101,17 @@ export default class FloatingManager {
         return false;
     }
 
-    private static doClose(id: number, entry: FloatingEntry, target?: HTMLElement, event?:Event) {
+    /**
+     * 
+     * Fecha uma entrada flutuante (FloatingManager).
+     * 
+     * @param id - Código da entrada que se deseja encerrar.
+     * @param entry - FloatingManager.
+     * @param target - Elemento HTML referente.
+     * @param event - Evento específico que será verificado, como clique do mouse.
+     * 
+    */
+    private static doClose(id: number, entry: FloatingEntry, target?: HTMLElement, event?:Event): void {
         if (!target || entry.options.autoClose) {
             const parent: HTMLElement | undefined = entry.parent;
             const content: HTMLElement | undefined = entry.content;
@@ -93,14 +131,28 @@ export default class FloatingManager {
         FloatingManager.hideOverlay();
     }
 
-    private static handleDocumentEvent(event: Event) {
+    /**
+     * 
+     * Fecha todas as FloatingManagers abertas.
+     * 
+     * @param event - Evento ocorrido, como clique do mouse, por exemplo.
+     * 
+     */
+    private static handleDocumentEvent(event: Event): void {
 
         FloatingManager.entries.forEach((entry, index) => {
             FloatingManager.doClose(index, entry, event.composedPath()[0] as HTMLElement, event);
         });
     }
 
-    private static handleKeyboardEvent(event: KeyboardEvent) {
+    /**
+     * 
+     * Captura eventos de teclado para manipular os elementos flutuantes via eventos da tecla pressionada.
+     * 
+     * @param event - Evento de teclado.
+     * 
+     */
+    private static handleKeyboardEvent(event: KeyboardEvent): void {
         if (event.key === 'Escape') {
             for (let index: number = FloatingManager.entries.length; index >= 0; index--) {
                 const entry: FloatingEntry = FloatingManager.entries[index];
@@ -112,12 +164,30 @@ export default class FloatingManager {
         }
     }
 
-    private static applyStyle(element: HTMLElement, propertyName: string, value?: string) {
+    /**
+     * 
+     * Adiciona uma propriedade CSS em um elemento HTML.
+     * 
+     * @param element - Elemento HTML que será modificado.
+     * @param propertyName - Nome da propriedade CSS que será adicionada.
+     * @param value - Valor da propriedade adicionada.
+     * 
+     * 
+     */
+    private static applyStyle(element: HTMLElement, propertyName: string, value?: string):void {
         if (value) {
             element.style.setProperty(propertyName, value);
         }
     }
 
+    /**
+     * 
+     * Obtém o índice do FloatingManager do Elemento HMTL desejado.
+     * 
+     * @param content - Elemento a ser buscado.
+     * @param parent - Elemento pai do content a ser buscado.
+     * @returns - Índice do elemento informado.
+     */
     private static getFloatIndex(content: HTMLElement, parent: HTMLElement): number {
 
         for (let index: number = 0; index < FloatingManager.entries.length; index++) {
@@ -129,10 +199,30 @@ export default class FloatingManager {
         return -1;
     }
 
-    public static isFloating(id: number){
+    /**
+     * 
+     * Retorna se uma entrada flutuante existe.
+     * 
+     * @param id - Índice para ser verificado no FloatingManager.
+     * 
+     * @returns - Verdadeiro se existir.
+     * 
+     */
+    public static isFloating(id: number): boolean{
         return FloatingManager.entries[id] !== undefined;
     }
 
+
+    /**
+     * 
+     * Cria e exibe um novo item no FloatingManager.
+     * 
+     * @param content - Elemento HTML que será criado.
+     * @param parent - Elemento HTML que será o pai do item a ser criado.
+     * @param options - Opções de configuração a serem adicionadas.
+     * 
+     * @returns - ID do novo item criado.
+     */
     public static float(content: HTMLElement, parent: HTMLElement, options: FloatingOptions = { autoClose: true }): number {
 
         if (!FloatingManager.initialized) {
@@ -158,12 +248,25 @@ export default class FloatingManager {
         return FloatingManager.entries.length - 1;
     }
 
-    private static showOverlay(options: FloatingOptions){
+    /**
+     * 
+     * Aplica o desfoque na página se o elemento possuir essa option ativada.
+     * 
+     * @param options - Configurações que serão utilizadas no elemento.
+     * 
+     */
+    private static showOverlay(options: FloatingOptions): void{
         if(options.useOverlay){
            this.createOrUpdatOverlay().style.display = "block";
         }
     }
 
+    /**
+     * 
+     * Desfaz o desfoque/overlay dos elementos na tela.
+     * 
+     * 
+     */
     private static hideOverlay(){
 
         if(FloatingManager.entries.filter(entry => entry.options.useOverlay).length > 0){
@@ -176,6 +279,14 @@ export default class FloatingManager {
         }
     }
 
+
+    /**
+     * 
+     * Cria ou atualiza o elemento de sobreposição.
+     * 
+     * @param className - Classe CSS que será adicionada ao modal.
+     * @returns - O elemento atualizado.
+     */
     private static createOrUpdatOverlay(className: string = FloatingManager.MODAL_DEFAULT_CLASSNAME):HTMLDivElement{
         let overlayElement: HTMLDivElement = document.querySelector(`div#${FloatingManager.MODAL_ELEMENT_ID}`) as HTMLDivElement;
         if(!overlayElement){
@@ -195,6 +306,11 @@ export default class FloatingManager {
         return overlayElement;
     }
 
+    /**
+     * 
+     * Cria elemento de estilo.
+     * Elemento que define o estilo padrão do elemento de sobreposição.
+     */
     private static createStyleElement():void{
         let styleElement:HTMLStyleElement = document.querySelector(`style#${FloatingManager.STYLE_ELEMENT_ID}`) as HTMLStyleElement;
         if(styleElement == undefined){
@@ -219,6 +335,14 @@ export default class FloatingManager {
         }
     }
 
+    /**
+     * 
+     * Atualiza posição de um elemento que já está em tela.
+     * 
+     * @param content - Elemento HTML que será atualizado.
+     * @param parent - Elemento pai do content passado.
+     * @param options - Novas opções desejadas.
+     */
     public static updateFloatPosition(content: HTMLElement, parent: HTMLElement, options: FloatingOptions = { autoClose: true }) {
         const alreadyFloatingIndex = FloatingManager.getFloatIndex(content, parent);
         if (alreadyFloatingIndex > -1) {
@@ -230,6 +354,13 @@ export default class FloatingManager {
 
     }
 
+    /**
+     * 
+     * Fecha elemento flutuante da tela.
+     * 
+     * @param id - Índice do elemento desejado.
+     * 
+     */
     public static close(id: number) {
         if (FloatingManager.entries[id]) {
             FloatingManager.doClose(id, FloatingManager.entries[id], undefined);

package/src/utils/ApplicationContext.ts

@@ -1,13 +1,34 @@
+/***
+ * `ApplicationContext`: Utilizado para manipulação do contexto.
+ * - Evitar uso da classe sem alinhamento com a arquitetura devido ao uso de variáveis globais.
+ */
 export default class ApplicationContext{
 
+    /**
+     * Obtém informação específica do contexto.
+     * 
+     * @param key - Chave do contexto desejada.
+     * @returns - Informação do contexto desejado.
+     */  
     public static getContextValue(key: string):any{
         return ApplicationContext.getCtx()[key];
     }
 
+     /**
+     * Aplica informação no contexto.
+     * 
+     * @param key - Identificador do contexto.
+     * @param value - Informação a ser inserida no contexto.
+     */ 
     public static setContextValue(key: string, value: any):any{
         ApplicationContext.getCtx()[key] = value;
     }
 
+    /**
+     * Obtém o contexto global da aplicação sankhyacore.
+     * - Esse contexto pode ser entendido como um ponto de coesão para atores que não se conhecem poderem trocar informação. Assim, o código x busca por um possível valor no contexto. Se essa informação estiver lá, ele reage de certa forma. O código Y, sabe dessa necessidade mas não consegue passar essa informação diretamente, então atribui o valor ao contexto.
+     * @returns - Objeto com as propriedades da variável global ___snkcore___ctx___.
+     */ 
     private static getCtx():any{
         let ctx = (window as any).___snkcore___ctx___;
         if(!ctx){

package/src/utils/ArrayUtils.ts

@@ -1,14 +1,16 @@
 import { StringUtils } from "./StringUtils.js";
-
+/**
+ * `ArrayUtils`: Utilitário com a responsabilidade de manipular Arrays.
+ */
 export default class ArrayUtils {
     /**
      * Filtra um array a partir de um critério textual.
      * 
-     * @param argument - Texto a ser usado no filtro 
-     * @param originalArray - Array no formato original
+     * @param argument - Texto a ser usado no filtro.
+     * @param originalArray - Array no formato original.
      * @param alphabeticalSorting - Determina se o resultado deve ser ordenado ou mantido na ordem original. Por padrão ordena.
-     * @param fieldName - Caso o objeto deva ser filtrado por um campo diferente de "label", pode-se usar esse parâmetro
-     * @returns Um array filtrado e ordenado conforme necessidade. Se "argument" for omitido, ou nulo, o array original é retornado. 
+     * @param fieldName - Caso o objeto deva ser filtrado por um campo diferente de "label", pode-se usar esse parâmetro.
+     * @returns - Um array filtrado e ordenado conforme necessidade..
      */
     static applyStringFilter(argument: string, originalArray: Array<any>, alphabeticalSorting: boolean = true, fieldName: string = "label"): Array<any>{
        if(!argument){
@@ -22,10 +24,22 @@ export default class ArrayUtils {
         return alphabeticalSorting ? ArrayUtils.sortAlphabetically(filteredArray, fieldName) : filteredArray;
     }
 
+    /**
+     * Converte texto para caixa alta e substitui caracteres acentuados.
+     * 
+     * @param original - Texto a ser convertido.
+     * @returns - Texto com as letras acentuadas sem os acentos e em caixa alta.
+     */
     private static normalizeSearchString(original:string ): string{
         return StringUtils.replaceAccentuatedCharsKeepSymbols(original.toUpperCase());
     }
 
+    /**
+     * Ordena valores de um array alfabeticamente.
+     * 
+     * @param originalArray - Array a ser ordenado.
+     * @returns - Array ordenado alfabeticamente..
+     */
     static sortAlphabetically(originalArray: Array<any>, fieldName: string = "label"): Array<any>{
         return originalArray.sort((fieldA, fieldB) => StringUtils.compare(fieldA[fieldName], fieldB[fieldName]));
     }

package/src/utils/CriteriaModel.ts

@@ -6,7 +6,8 @@ interface OutputJSON {
 }
 
 /**
- * CriteriaParameter
+ * `CriteriaParameter`: Utilizado para validar e manipular os critérios da requisição.
+ * 
  */
 export class Criteria {
 
@@ -32,7 +33,6 @@ export class Criteria {
      * @methodOf sankhyalabs.core.src:CriteriaProvider
      * @description Setter para "parameters". Trata-se de uma Array de parametros da classe Criteria.
      * @param {Array<CriteriaParameter>} [parameters] Array de parametros da classe Criteria.
-     * @returns {void}
      */
     public set parameters(parameters: Array<CriteriaParameter>) {
         this._parameters = parameters;
@@ -57,7 +57,6 @@ export class Criteria {
      * @methodOf sankhyalabs.core.src:CriteriaProvider
      * @description Setter para "expression". Trata-se do expressão da classe Criteria.
      * @param {string} [expression] Expressão da classe Criteria.
-     * @returns {void}
      */
     public set expression(expression: string | undefined) {
         this._expression = expression;
@@ -196,10 +195,9 @@ export class Criteria {
      *  - Se passado um array, o metodo iterará no array e adicionará cada um dos itens.
      *  - É possível passar um Objeto CriteriaParameter, um número, string ou uma instancia de data, eles serão inferidos para o tipo certo.
      * @param {CriteriaParameter} Parâmetro a ser adicionado.
-     * @returns {Criteria} Retorna a própria instância do Criterio para encadeamento.
      */
     private addParameter(param: Array<CriteriaParameter>): void {
-        for (let index in param) {
+        for (const index in param) {
             this.parameters.push(param[index]);
         }
     }