@bildvitta/quasar-ui-asteroid 3.20.0-beta.14-alpha.4 → 3.20.0-beta.14

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bildvitta/quasar-ui-asteroid",
   "description": "Asteroid",
-  "version": "3.20.0-beta.14-alpha.4",
+  "version": "3.20.0-beta.14",
   "author": "Bild & Vitta <systemteam@bild.com.br>",
   "license": "MIT",
   "main": "./src/asteroid.js",

package/src/components/actions-menu/QasActionsMenu.vue

@@ -6,11 +6,11 @@
           <q-item v-bind="getItemProps(item)" :key="key" active-class="primary" clickable data-cy="actions-menu-list-item" @click="setClickHandler(item)">
             <q-item-section avatar>
               <q-spinner v-if="item.loading" size="sm" />
-              <q-icon v-else :class="getMagicAiClass(item)" :name="item.icon" />
+              <q-icon v-else :class="getMagicAiClasses(item)" :name="item.icon" />
             </q-item-section>
 
             <q-item-section>
-              <q-item-label :class="getMagicAiClass(item)">
+              <q-item-label :class="getMagicAiClasses(item)">
                 {{ item.label }}
               </q-item-label>
             </q-item-section>
@@ -286,8 +286,8 @@ function getItemProps (item) {
   }
 }
 
-function getMagicAiClass (item) {
-  return { 'text-magic-ai': item.useMagicAiColor }
+function getMagicAiClasses ({ useMagicAiColor }) {
+  return { 'text-magic-ai': useMagicAiColor }
 }
 
 function handleMenuModel (newValue, oldValue) {

package/src/components/board-generator/QasBoardGenerator.vue

@@ -3,8 +3,8 @@
     <qas-grabbable class="qas-board-generator" v-bind="grabbableProps">
       <div ref="columnsContainer" class="no-wrap q-gutter-md q-pb-xs q-px-lg row">
         <qas-lazy-loading-components :key="lazyLoadingKey" v-model:visible-items="visibleItems" direction="horizontal" placeholder-width="350px" :threshold="0">
-          <qas-box v-for="(header, index) in normalizedHeaders" :key="index" :class="getColumnClass(header)" :style="containerStyle">
-            <div class="ellipsis q-mb-md text-grey-10" v-bind="headerBoxProps">
+          <qas-box v-for="(header, index) in normalizedHeaders" :key="index" :class="getColumnClasses(header)" :style="containerStyle">
+            <div class="ellipsis q-mb-md text-grey-10">
               <qas-skeleton v-if="props.skeleton" type="text" use-contrast width="80%" />
 
               <slot v-else :fields="getFieldsByHeader(header)" :header="header" :index="index" name="header-column" />
@@ -22,24 +22,19 @@
                 </div>
 
                 <div class="text-center">
-                  <qas-btn class="q-mt-md" icon="sym_r_refresh" label="Tentar novamente" :loading="columnsLoading[getKeyByHeader(header)]" @click="fetchColumn(header, true)" />
+                  <qas-btn class="q-mt-md" icon="sym_r_refresh" label="Tentar novamente" :loading="columnsLoading[getKeyByHeader(header)]" @click="handleFetchColumnClick(header)" />
                 </div>
               </div>
 
               <template v-else>
                 <qas-lazy-loading-components :threshold="0">
                   <div v-for="(item) in getItemsByHeader(header)" :id="item[props.itemIdKey]" :key="item[props.itemIdKey]" class="qas-board-generator__item" :data-disable-drag="updatingPositionItemKeys.has(item[props.itemIdKey])">
-                    <!-- <slot v-if="!props.skeleton" :column-index="index" :fields="getFieldsByHeader(header)" :header="header" :item="item" name="column-item" /> -->
-                    <!-- <qas-card v-if="updatingPositionItemKey === item[props.itemIdKey]" v-bind="skeletonCards.at(0)" :key="item[props.itemIdKey]" class="q-mb-sm" :column-index="index">
-                      <template #default />
-                    </qas-card> -->
-
                     <slot v-if="!props.skeleton" :column-index="index" :fields="getFieldsByHeader(header)" :header="header" :is-updating-position="updatingPositionItemKeys.has(item[props.itemIdKey])" :item="item" name="column-item" />
                   </div>
                 </qas-lazy-loading-components>
 
                 <div class="full-width justify-center row">
-                  <qas-btn v-if="hasSeeMore(header)" icon="sym_r_add" :label="props.seeMoreButtonLabel" :loading="columnsLoading[getKeyByHeader(header)]" :use-label-on-small-screen="false" variant="tertiary" @click="fetchColumn(header, true)" />
+                  <qas-btn v-if="hasSeeMore(header)" icon="sym_r_add" :label="props.seeMoreButtonLabel" :loading="columnsLoading[getKeyByHeader(header)]" :use-label-on-small-screen="false" variant="tertiary" @click="handleFetchColumnClick(header)" />
 
                   <template v-if="hasSkeletonByHeader(header)">
                     <div class="q-col-gutter-y-sm row">
@@ -117,11 +112,6 @@ const props = defineProps({
     default: () => ({})
   },
 
-  headerBoxProps: {
-    type: Object,
-    default: () => ({})
-  },
-
   columnIdKey: {
     type: String,
     required: true
@@ -182,13 +172,7 @@ const props = defineProps({
   },
 
   skeleton: {
-    type: Boolean,
-    default: true
-  },
-
-  useMarkRaw: {
-    type: Boolean,
-    default: true
+    type: Boolean
   },
 
   useDragAndDropX: {
@@ -247,8 +231,13 @@ const columnsLoading = ref({})
 const columnsFieldsModel = ref({})
 const showConfirmDialog = ref(false)
 const isLoadingUpdatePosition = ref(false)
-const isLoadingFromSeeMore = ref(false)
+const hideSkeleton = ref(false)
 const columnsWithError = ref({})
+
+/**
+ * Set de IDs dos itens com update de posição em andamento.
+ * Usamos Set para evitar duplicatas e ter O(1) no has().
+ */
 const updatingPositionItemKeys = ref(new Set())
 
 /**
@@ -309,7 +298,10 @@ let currentFetchColumnsSession = 0
 
 /**
  * Estado do smooth scroll horizontal.
- * Acumula o target e interpola suavemente via requestAnimationFrame.
+ * Acumula o target e interpola suavemente via requestAnimationFrame (rAF).
+ *
+ * rAF (requestAnimationFrame) sincroniza a animação com o refresh da tela (~60fps).
+ * Isso evita "saltos" de scroll, tornando o movimento suave e fluido.
  */
 const SMOOTH_SCROLL_LERP = 0.2
 
@@ -352,13 +344,15 @@ const grabbableProps = {
  * Gera cards de skeleton para exibir enquanto carrega os itens da coluna, o mesmo é usado para preencher a coluna
  * quando a prop "skeleton" for true, indicando que é para simular o carregamento.
  */
-const skeletonCards = Array.from({ length: 6 }).map(() => ({
-  skeleton: true,
-  title: '-',
-  expansionProps: { label: '-' },
-  actionsMenuProps: { list: {} },
-  useSelection: true
-}))
+const skeletonCards = Array.from({ length: 6 }).map(() => {
+  return {
+    skeleton: true,
+    title: '-',
+    expansionProps: { label: '-' },
+    actionsMenuProps: { list: {} },
+    useSelection: true
+  }
+})
 
 // computeds
 const columnContainerElements = computed(() => {
@@ -378,38 +372,6 @@ const normalizedHeaders = computed(() => {
   return props.headers
 })
 
-// watchers
-watch(
-  () => normalizedHeaders.value,
-  value => {
-    if (isLoadingUpdatePosition.value || !value?.length) return
-
-    fetchColumnsValues()
-  }
-)
-
-watch(() => columnContainerElements.value, () => {
-  setColumnHeightContainer()
-  handleElementsList()
-})
-
-// hooks
-onMounted(() => {
-  if (normalizedHeaders.value.length) {
-    fetchColumnsValues()
-  }
-
-  window.addEventListener('resize', setColumnHeightContainer)
-})
-
-onBeforeUnmount(() => {
-  abortAllColumnRequests()
-  destroySortable()
-
-  window.removeEventListener('resize', setColumnHeightContainer)
-})
-
-// Computeds
 const columnsResultsModel = computed({
   get () {
     return props.results
@@ -422,8 +384,6 @@ const columnsResultsModel = computed({
 
 const isDragging = computed(() => draggingCount.value > 0)
 
-provide('isDragging', isDragging)
-
 const hasColumnsLength = computed(() => !!Object.keys(columnsResultsModel.value).length)
 
 const containerStyle = computed(() => `width: ${props.columnWidth};`)
@@ -449,12 +409,54 @@ const defaultConfirmDialogProps = computed(() => {
   }
 })
 
+// provide
+provide('isDragging', isDragging)
+
+// watchers
+watch(
+  () => normalizedHeaders.value,
+  value => {
+    if (isLoadingUpdatePosition.value || !value?.length) return
+
+    fetchColumnsValues()
+  }
+)
+
+watch(() => columnContainerElements.value, () => {
+  setColumnHeightContainer()
+  handleElementsList()
+})
+
+// hooks
+onMounted(() => {
+  if (normalizedHeaders.value.length) {
+    fetchColumnsValues()
+  }
+
+  window.addEventListener('resize', setColumnHeightContainer)
+})
+
+onBeforeUnmount(() => {
+  abortAllColumnRequests()
+  destroySortable()
+
+  window.removeEventListener('resize', setColumnHeightContainer)
+})
+
 // functions
 /*
 * Setar o tamanho do container do board, onde deverá ser a altura passada via prop, ou o default será ocupar o maximo
 * de espaço que ele conseguir considerando a altura do container em relação ao topo.
 */
 function setColumnHeightContainer () {
+  if (props.height) {
+    columnContainerElements.value.forEach(columnElement => {
+      columnElement.style.height = props.height
+    })
+
+    return
+  }
+
   // Primeira etapa: calcula e aplica a altura inicial de cada coluna
   columnContainerElements.value.forEach(columnElement => {
     // Pega a posição atual da coluna em relação ao topo da viewport
@@ -514,7 +516,7 @@ async function fetchColumns () {
   const mySession = ++currentFetchColumnsSession
 
   // Mapeia os índices visíveis para os IDs de coluna correspondentes
-  const visibleKeys = new Set(visibleItems.value.map(i => getKeyByHeader(normalizedHeaders.value[i])))
+  const visibleKeys = new Set(visibleItems.value.map(item => getKeyByHeader(normalizedHeaders.value[item])))
 
   const visibleHeaders = visibleKeys.size
     ? normalizedHeaders.value.filter(header => visibleKeys.has(getKeyByHeader(header)))
@@ -548,6 +550,7 @@ async function fetchColumns () {
   if (currentFetchColumnsSession !== mySession) return
 
   const allPromises = [...visibleColumns, ...hiddenColumns]
+  console.log('🚀 ~ fetchColumns ~ allPromises:', allPromises)
 
   const hasAllPromisesSucceeded = allPromises.every(promise => promise.status === 'fulfilled')
   const hasAllPromisesFailed = allPromises.length > 0 && allPromises.every(promise => promise.status === 'rejected')
@@ -568,18 +571,36 @@ async function fetchColumns () {
 }
 
 /*
-* Busca a coluna com base no header recebido.
+* Wrapper para chamadas de fetchColumn originadas de eventos de clique do usuário.
+* fetchColumn relança o erro para que Promise.allSettled em fetchColumns consiga
+* detectar colunas com falha; aqui o erro já foi tratado internamente, portanto
+* é suprimido para evitar o warning "Unhandled error during execution of component
+* event handler" do Vue.
 */
-async function fetchColumn (header, fromSeeMore, setEr) {
+function handleFetchColumnClick (header) {
+  fetchColumn(header, true)
+}
+
+/**
+ * Busca a coluna com base no header recebido.
+ *
+ * @param header - payload do header da coluna a ser buscada, exemplo: { date: '2024-02-12', ... }
+ * @param shouldHideSkeleton - flag para controlar se o skeleton de carregamento deve ser ocultado durante a busca
+ */
+async function fetchColumn (header, shouldHideSkeleton) {
   const headerKey = getKeyByHeader(header)
 
-  // Cancela qualquer request anterior para esta mesma coluna antes de iniciar a nova.
-  // Garante que nunca haja duas requests paralelas para a mesma coluna.
+  /**
+   * Cancela qualquer request anterior para esta mesma coluna antes de iniciar a nova.
+   * Garante que nunca haja duas requests paralelas para a mesma coluna.
+   */
   abortColumnRequest(headerKey)
 
-  // Incrementa a geração desta coluna para invalidar callbacks onLoading da request cancelada,
-  // evitando que o onLoading(false) antigo sobrescreva o estado da nova request.
-  // Usa ?? 0 pois ++undefined retorna NaN, e NaN === NaN é sempre false, travando o skeleton.
+  /**
+   * Incrementa a geração desta coluna para invalidar callbacks onLoading da request cancelada,
+   * evitando que o onLoading(false) antigo sobrescreva o estado da nova request.
+   * Usa ?? 0 pois ++undefined retorna NaN, e NaN === NaN é sempre false, travando o skeleton.
+   */
   columnFetchGenerations[headerKey] = (columnFetchGenerations[headerKey] ?? 0) + 1
   const generation = columnFetchGenerations[headerKey]
 
@@ -588,10 +609,10 @@ async function fetchColumn (header, fromSeeMore, setEr) {
 
   const { limit, offset } = columnsPagination.value[headerKey] || {}
 
-  isLoadingFromSeeMore.value = fromSeeMore
+  hideSkeleton.value = shouldHideSkeleton
 
   const { data: response, error } = await promiseHandler(
-    axios.get(`${props.columnUrl}/${headerKey}/${setEr ? 'setError' : ''}`, {
+    axios.get(`${props.columnUrl}/${headerKey}`, {
       signal: abortController.signal,
       params: {
         ...props.columnParams,
@@ -601,8 +622,10 @@ async function fetchColumn (header, fromSeeMore, setEr) {
     }),
     {
       onLoading: value => {
-        // Só atualiza o loading se ainda for a request atual desta coluna,
-        // evitando que o onLoading(false) de uma request cancelada sobrescreva o da nova.
+        /**
+         * Só atualiza o loading se ainda for a request atual desta coluna,
+         * evitando que o onLoading(false) de uma request cancelada sobrescreva o da nova.
+         */
         if (columnFetchGenerations[headerKey] === generation) {
           columnsLoading.value[headerKey] = value
         }
@@ -613,7 +636,7 @@ async function fetchColumn (header, fromSeeMore, setEr) {
 
   delete columnAbortControllers[headerKey]
 
-  isLoadingFromSeeMore.value = false
+  hideSkeleton.value = false
 
   if (error) {
     // Request cancelada intencionalmente (novo fetchColumnsValues chamado): ignora silenciosamente.
@@ -647,7 +670,7 @@ async function fetchColumn (header, fromSeeMore, setEr) {
    * onde cada item do objeto é uma coluna no board. O mesmo vale para "columnsFieldsModel", "columnsLoading" e
    * "columnPagination", organizando os fields, loadings e o controle de paginação por chave identificadora do header.
    */
-  columnsResultsModel.value[headerKey] = props.useMarkRaw ? markRaw(newColumnValues) : newColumnValues
+  columnsResultsModel.value[headerKey] = hasDragAndDrop ? newColumnValues : markRaw(newColumnValues)
 
   /*
   * Pode acontecer das options nos fields da segunda página serem diferentes da primeira página,
@@ -755,15 +778,19 @@ function setColumnsPagination () {
 
     columnsPagination.value[headerKey] = { limit: props.limitPerColumn, offset: 0 }
 
-    // Inicia como true para exibir skeleton imediatamente, evitando flash de tela vazia
-    // entre o reset e o início das novas requests.
+    /**
+     * Inicia como true para exibir skeleton imediatamente, evitando flash de tela vazia
+     * entre o reset e o início das novas requests.
+     */
     columnsLoading.value[headerKey] = true
   })
 }
 
 function fetchColumnsValues () {
-  // Cancela todas as requests em andamento antes de iniciar novas,
-  // evitando resposta de requests antigas sobrescrevendo dados da nova sessão.
+  /**
+   * Cancela todas as requests em andamento antes de iniciar novas, evitando resposta de requests
+   * antigas sobrescrevendo dados da nova sessão.
+   */
   abortAllColumnRequests()
 
   lazyLoadingKey.value++
@@ -777,10 +804,10 @@ function fetchColumnsValues () {
 /**
  * Descrição:
  * Exibe o texto quando:
- * - Nao esta carregando a coluna
- * - Nao tem itens na coluna
- * - Nao estou fazendo o drag and drop
- * - Nao esta exibindo o dialog de confirmação
+ * - Não está carregando a coluna
+ * - Não tem itens na coluna
+ * - Não estou fazendo o drag and drop
+ * - Não está exibindo o dialog de confirmação
  *
  * @param {Object} header
  */
@@ -881,8 +908,6 @@ function setSortable (element, index) {
 
     group: useOnlyDragAndDropY ? `column-${index}` : 'shared',
 
-    // direction: 'vertical',
-
     /**
      * invertSwap muda o algoritmo de swap: em vez de trocar quando o centro do item arrastado
      * cruza o centro do alvo (instável, causa oscilação), troca apenas quando cruza a BORDA
@@ -944,7 +969,10 @@ function stopDragging () {
 /**
  * Intercepta cada chamada de scroll do SortableJS.
  * - Scroll vertical (colunas): retorna 'continue' para manter o comportamento nativo.
- * - Scroll horizontal (container do board): aplica smooth scroll via rAF.
+ * - Scroll horizontal (container do board): aplica smooth scroll interpolado via rAF.
+ *
+ * rAF (requestAnimationFrame) sincroniza com o refresh da tela (~60fps),
+ * tornando o scroll suave. Sem rAF, seria um "salto" abrupto.
  */
 function handleSortableScroll (offsetX, offsetY, evt, _touchEvt, scrollEl) {
   // Obtém o container com scroll horizontal (`.qas-grabbable__container`).
@@ -961,16 +989,25 @@ function handleSortableScroll (offsetX, offsetY, evt, _touchEvt, scrollEl) {
 
     smoothScrollTarget = Math.max(0, Math.min(smoothScrollTarget + offsetX, maxScroll))
 
+    // Se não há animação em andamento, inicia uma.
+    // rAF (requestAnimationFrame) agenda a função smoothScrollStep para o próximo frame (~16ms a 60fps).
+
+    /**
+     * Se não há animação em andamento, inicia uma. rAF (requestAnimationFrame) agenda a função smoothScrollStep
+     * para o próximo frame (~16ms a 60fps).
+     */
     if (!smoothScrollRafId) {
       smoothScrollRafId = requestAnimationFrame(smoothScrollStep)
     }
+
     return
   }
 
-  // Scroll vertical (dentro da coluna): aplica manualmente com velocidade independente do scrollSpeed horizontal.
-  // offsetY já vem escalado pelo scrollSpeed (60), então normalizamos para VERTICAL_SCROLL_SPEED (10).
-  // Além disso, como scrollSensitivity está em HORIZONTAL_SCROLL_SENSITIVITY (200), verificamos manualmente
-  // se o cursor está dentro de VERTICAL_SCROLL_SENSITIVITY (80) da borda da coluna antes de rolar.
+  /**
+   * SortableJS chama essa função com offsets de scroll.
+   * Para scroll vertical: retorna 'continue' para deixar o comportamento nativo.
+   * Para scroll horizontal: aplica smooth scroll customizado via rAF.
+   */
   if (offsetY) {
     const clientY = evt?.clientY ?? evt?.touches?.[0]?.clientY
 
@@ -991,6 +1028,14 @@ function handleSortableScroll (offsetX, offsetY, evt, _touchEvt, scrollEl) {
 /**
  * Loop de animação que interpola o scrollLeft em direção ao target
  * usando fator de lerp (move 20% da distância restante por frame).
+ *
+ * Funciona assim:
+ * 1. Calcula a diferença entre a posição atual e a posição desejada (target).
+ * 2. Se ainda há diferença significativa, move 20% da distância restante.
+ * 3. Agenda o próximo frame via rAF para continuar a interpolação.
+ * 4. Quando chega perto o suficiente (~0.5px), para a animação.
+ *
+ * Resultado: scroll suave e progressivo, não um "salto" abrupto.
  */
 function smoothScrollStep () {
   smoothScrollRafId = null
@@ -1000,16 +1045,21 @@ function smoothScrollStep () {
   const current = smoothScrollEl.scrollLeft
   const diff = smoothScrollTarget - current
 
+  // Se chegou bem perto do target, para na posição exata.
   if (Math.abs(diff) < 0.5) {
     smoothScrollEl.scrollLeft = smoothScrollTarget
     return
   }
 
+  // Move 20% da distância restante (interpolação suave).
   smoothScrollEl.scrollLeft = current + diff * SMOOTH_SCROLL_LERP
+
+  // Agenda o próximo frame para continuar a animação (chamada recursiva via rAF).
   smoothScrollRafId = requestAnimationFrame(smoothScrollStep)
 }
 
 function resetSmoothScroll () {
+  // Cancela a animação agendada (rAF) para evitar que continue executando após o drag terminar.
   if (smoothScrollRafId) {
     cancelAnimationFrame(smoothScrollRafId)
     smoothScrollRafId = null
@@ -1051,7 +1101,7 @@ function addItemToList ({ headerKey, item, index }) {
 
   updatedList.splice(insertIndex, 0, item)
 
-  columnsResultsModel.value[headerKey] = props.useMarkRaw ? markRaw(updatedList) : updatedList
+  columnsResultsModel.value[headerKey] = updatedList
   columnsPagination.value[headerKey].count += 1
 }
 
@@ -1172,7 +1222,7 @@ function removeItemFromList ({ headerKey, itemId }) {
   const updatedList = [...columnItemList]
   updatedList.splice(itemIndex, 1)
 
-  columnsResultsModel.value[headerKey] = props.useMarkRaw ? markRaw(updatedList) : updatedList
+  columnsResultsModel.value[headerKey] = updatedList
 
   /**
    * Remove o item do count da coluna para não mostrar o botão de "Ver mais¨.
@@ -1180,13 +1230,29 @@ function removeItemFromList ({ headerKey, itemId }) {
   columnsPagination.value[headerKey].count -= 1
 }
 
+/**
+ * Substitui um item na lista de uma coluna pelos dados atualizados do servidor.
+ *
+ * 1. Localiza a lista de itens da coluna
+ * 2. Encontra o índice do item usando o itemIdKey como identificador
+ * 3. Se encontrado, altera o item localmente (sem criar nova referência de array)
+ *
+ * @param {Object} params
+ * @param {string} params.headerKey - ID da coluna
+ * @param {string|number} params.itemId - ID do item a atualizar (deve corresponder a props.itemIdKey)
+ * @param {Object} params.updatedItem - Novo objeto do item com dados atualizados
+ *
+ */
 function updateItemInList ({ headerKey, itemId, updatedItem }) {
   const columnItemList = columnsResultsModel.value[headerKey]
 
+  // Encontra o índice do item na lista usando o identificador (itemIdKey)
   const itemIndex = columnItemList.findIndex(itemContent => itemContent[props.itemIdKey] === itemId)
 
+  // Se não encontrar (itemIndex === -1), retorna sem fazer nada
   if (!~itemIndex) return
 
+  // Substitui o item antigo pelo item atualizado na mesma posição
   columnItemList.splice(itemIndex, 1, updatedItem)
 }
 
@@ -1209,7 +1275,7 @@ async function updatePosition ({ newHeaderKey, oldHeaderKey, itemId, event, opti
 
   const isFnUpdatePositionUrl = typeof props.updatePositionUrl === 'function'
 
-  isLoadingFromSeeMore.value = true
+  hideSkeleton.value = true
 
   const url = isFnUpdatePositionUrl
     ? props.updatePositionUrl({ newHeaderKey, oldHeaderKey, itemId })
@@ -1314,7 +1380,7 @@ function isCancelledError (error) {
  * @param {string|number} params.itemId - ID do item a ser movido (valor correspondente à prop `itemIdKey`).
  * @param {string|number} params.fromColumnId - ID da coluna de origem (valor correspondente à prop `columnIdKey`).
  * @param {string|number} params.toColumnId - ID da coluna de destino (valor correspondente à prop `columnIdKey`).
- * @param {Object}        [params.updatedItem] - Dados atualizados do item. Quando informado, sobrescreve o item original na coluna de destino.
+ * @param {Object} [params.updatedItem] - Dados atualizados do item. Quando informado, sobrescreve o item original na coluna de destino.
  * @returns {void}
  */
 function transferItemToColumn ({ itemId, fromColumnId, toColumnId, updatedItem }) {
@@ -1334,10 +1400,10 @@ function transferItemToColumn ({ itemId, fromColumnId, toColumnId, updatedItem }
 function hasSkeletonByHeader (header) {
   const headerKey = getKeyByHeader(header)
 
-  return (props.skeleton || columnsLoading.value[headerKey]) && !isLoadingFromSeeMore.value
+  return (props.skeleton || columnsLoading.value[headerKey]) && !hideSkeleton.value
 }
 
-function getColumnClass (header) {
+function getColumnClasses (header) {
   const headerKey = getKeyByHeader(header)
 
   return {

package/src/components/board-generator/QasBoardGenerator.yml

@@ -97,8 +97,8 @@ props:
     type: Number
     default: 12
 
-  use-mark-raw:
-    desc: Define se os valores dos itens das colunas irão ser atribuídos utilizando o "markRaw", onde somente a primeira camada do model será reativa. (https://vuejs.org/api/reactivity-advanced.html#markraw)
+  skeleton:
+    desc: Exibe o estado de esqueleto de carregamento das colunas. Enquanto `true`, cada coluna renderiza cards fictícios no lugar dos itens reais.
     type: Boolean
     default: true
 
@@ -150,11 +150,26 @@ slots:
   column-item:
     desc: Slot para acessar o item da coluna.
     scope:
+      column-index:
+        desc: Índice da coluna atual.
+        type: Number
+        default: 0
+
       fields:
         desc: Fields referente à coluna atual do template.
         type: Object
         default: {}
 
+      header:
+        desc: Informações do header da coluna atual.
+        type: Object
+        default: {}
+
+      is-updating-position:
+        desc: Indica se o item está sendo atualizado via drag-and-drop (aguardando retorno da API de update).
+        type: Boolean
+        default: false
+
       item:
         desc: Informações de cada item da coluna que foi buscado através da API.
         type: Object
@@ -220,6 +235,45 @@ methods:
   'fetchColumn: (header) => void':
     desc: Busca uma coluna específica com base no header fornecido.
 
+  'refreshColumn: (header) => void':
+    desc: Reinicia a paginação da coluna e refaz a busca, substituindo completamente os itens existentes.
+    params:
+      header:
+        desc: Header da coluna a ser recarregada (mesmo formato da prop `headers`).
+        type: Object
+        required: true
+
+  'removeItemFromList: ({ headerKey, itemId }) => void':
+    desc: Remove um item da lista de uma coluna localmente, sem realizar nenhuma requisição. Também decrementa o contador de paginação.
+    params:
+      headerKey:
+        desc: Chave identificadora da coluna de origem (valor correspondente à prop `column-id-key`).
+        type: String | Number
+        required: true
+      itemId:
+        desc: ID do item a ser removido (valor correspondente à prop `item-id-key`).
+        type: String | Number
+        required: true
+
+  'updateItemInList: ({ headerKey, itemId, updatedItem }) => void':
+    desc: Substitui os dados de um item existente em uma coluna localmente, sem realizar nenhuma requisição.
+    params:
+      headerKey:
+        desc: Chave identificadora da coluna (valor correspondente à prop `column-id-key`).
+        type: String | Number
+        required: true
+      itemId:
+        desc: ID do item a ser atualizado (valor correspondente à prop `item-id-key`).
+        type: String | Number
+        required: true
+      updatedItem:
+        desc: Dados atualizados que substituirão o item original.
+        type: Object
+        required: true
+
+  'refetchColumns: () => void':
+    desc: Alias de `fetchColumns`. Busca novamente todas as colunas com base nos headers fornecidos.
+
   'transferItemToColumn: ({ itemId, fromColumnId, toColumnId, updatedItem? }) => void':
     desc: |
       Transfere um item de uma coluna para outra localmente, sem realizar nenhuma requisição.

package/src/components/board-generator/private/PvBoardGeneratorCardsContainer.vue

@@ -5,7 +5,6 @@
 </template>
 
 <script setup>
-
 import setScrollGradient from '../../../helpers/set-scroll-gradient'
 
 import { ref, onMounted, onBeforeUnmount } from 'vue'

package/src/components/box/QasBox.yml

@@ -32,3 +32,8 @@ props:
   use-spacing:
     desc: Controla espaçamento do componente.
     type: Boolean
+
+provide:
+  is-box:
+    desc: Identificador booleano que indica quando um componente está dentro do contexto de um QasBox.
+    type: Boolean

package/src/components/card/QasCard.vue

@@ -34,6 +34,7 @@
 
         <div class="qas-card__content relative-position" :class="contentClasses">
           <qas-skeleton v-if="props.skeleton" height="100px" />
+
           <slot v-else name="default" />
         </div>
 

package/src/components/date-time-input/QasDateTimeInput.vue

@@ -165,6 +165,12 @@ const hasDatePicker = computed(() => !props.useTimeOnly && !props.readonly)
 const hasTimePicker = computed(() => !props.useDateOnly && !props.readonly)
 
 watch(() => props.modelValue, (current, original) => {
+  /**
+   * No caso de ser adicionado uma data incompleta ou inválida, vamos limpar o model,
+   * mas não vamos limpar o "currentValue", para não limpar o campo, somente o model.
+   */
+  if (!current && original && error.value) return
+
   if (!current || props.useTimeOnly) {
     currentValue.value = current
     return
@@ -217,6 +223,9 @@ function updateModelValue (value) {
   if (error.value) {
     hasInvalidDate.value = true
     errorMessage.value = 'Data inválida.'
+
+    emit('update:modelValue', '')
+
     return
   }
 
@@ -262,18 +271,33 @@ function validateDateAndTime (value) {
 function validateDateTimeOnBlur () {
   const valueLength = currentValue.value?.replace?.(/_/g, '')?.length
 
+  // Caso for datetime
+  if (!props.useDateOnly && !props.useTimeOnly) {
+    const [date, time] = (currentValue.value || '').split(' ') || []
+    const isValidDate = date?.replace?.(/_/g, '')?.length === props.dateMask.length
+
+    /**
+     * Caso tenha preenchido a data, a data seja válida e não tenha preenchido o horário,
+     * preenche o horário com 00:00, ou de acordo com a mask.
+     */
+    if (isValidDate && !validateDateOnly(date) && !time?.length) {
+      // Horario setado deve seguir a mascara.
+      const defaultTimeByMask = props.timeMask.replace(/[HhMmSs]/g, '0')
+      const newValue = `${date} ${defaultTimeByMask}`
+
+      currentValue.value = newValue
+      updateModelValue(newValue)
+
+      return
+    }
+  }
+
   // valida se o tamanho digitado é o tamanho que a mascara espera receber
   error.value = !!((valueLength < mask.value.length || error.value) && valueLength)
 
   if (error.value && !hasInvalidDate.value) {
     errorMessage.value = 'Data incompleta.'
-  }
-
-  if (hasInvalidDate.value) {
-    currentValue.value = ''
-  }
 
-  if (error.value || hasInvalidDate.value) {
     emit('update:modelValue', '')
   }
 }

package/src/components/dialog/QasDialog.vue

@@ -5,10 +5,8 @@
         <slot name="header">
           <div class="items-center justify-between row">
             <qas-label data-cy="dialog-title" :label="props.card.title" margin="none">
-              <slot name="title"></slot>
+              <slot name="title" />
             </qas-label>
-            <!-- <slot name="title">
-            </slot> -->
 
             <qas-btn v-if="isInfoDialog" v-close-popup color="grey-10" data-cy="dialog-close-btn" icon="sym_r_close" variant="tertiary" />
           </div>

package/src/components/dialog/QasDialog.yml

@@ -69,6 +69,11 @@ slots:
   header:
     desc: Slot para o título.
 
+provide:
+  is-dialog:
+    desc: Identificador booleano que indica quando um componente está dentro do contexto de um QasDialog.
+    type: Boolean
+
 events:
   '@update:model-value -> function (value)':
     desc: Dispara toda vez que o model é atualizado, também utilizado para v-model.
@@ -111,6 +116,9 @@ selectors:
     desc: Seletor do botão de confirmar do componente.
     examples: ['data-cy="dialog-ok-btn"']
 
+  title:
+    desc: Slot para inserir conteúdo adicional ao lado do título do card do dialog.
+
   dialog-title:
     desc: Seletor do título do componente.
     examples: ['data-cy="dialog-title"']

package/src/components/expansion-item/QasExpansionItem.yml

@@ -62,6 +62,11 @@ slots:
   content:
     desc: Slot para substituir o conteúdo principal do card.
 
+provide:
+  is-expansion-item:
+    desc: Identificador booleano que indica quando um componente está dentro do contexto de um QasExpansionItem.
+    type: Boolean
+
 events:
   '@update:model-value -> function(value)':
     desc: Dispara quando o model-value altera, também usado para v-model.

package/src/components/form-generator/QasFormGenerator.yml

@@ -120,6 +120,11 @@ slots:
   'legend-bottom[nome-da-chave-do-fieldset]-[nome-da-chave-do-subset]':
     desc: Acessa o slot da seção abaixo do conteúdo do form de um subset específico.
 
+provide:
+  is-form-generator:
+    desc: Identificador booleano que indica quando um componente está dentro do contexto de um QasFormGenerator.
+    type: Boolean
+
 events:
   '@update:model-value -> function(value)':
     desc: Dispara quando o model-value altera, também usado para v-model.

package/src/components/header/QasHeader.yml

@@ -54,6 +54,11 @@ props:
     type: Boolean
     default: false
 
+provide:
+  is-header:
+    desc: Identificador booleano que indica quando um componente está dentro do contexto de um QasHeader.
+    type: Boolean
+
 slots:
   actions:
     desc: slot para acessar seção da direita (ações).

package/src/components/lazy-loading-components/QasLazyLoadingComponents.vue

@@ -30,35 +30,28 @@ import { ref, onMounted, onBeforeUnmount, useSlots, nextTick, watch } from 'vue'
 
 defineOptions({ name: 'QasLazyLoadingComponents' })
 
-// const emit = defineEmits(['update:visibleItems'])
-
 const props = defineProps({
-  // Porcentagem de visibilidade necessária para ativar (0.0 a 1.0)
   threshold: {
     type: Number,
     default: 0.1 // 10% visível
   },
 
-  // Margem extra ao redor do viewport para pré-carregamento
   rootMargin: {
     type: String,
     default: '0px'
   },
 
-  // Direção do scroll: 'vertical' (padrão) ou 'horizontal'
   direction: {
     type: String,
     default: 'vertical',
     validator: value => ['vertical', 'horizontal'].includes(value)
   },
 
-  // Altura dos placeholders antes de carregar (usado em direction='vertical')
   placeholderHeight: {
     type: String,
     default: '500px'
   },
 
-  // Largura dos placeholders antes de carregar (usado em direction='horizontal')
   placeholderWidth: {
     type: String,
     default: '300px'

package/src/components/lazy-loading-components/QasLazyLoadingComponents.yml

@@ -4,21 +4,46 @@ meta:
   desc: Componente para carregar elementos do slot somente quando ficam visíveis na viewport, otimizando performance da página.
 
 props:
-  threshold:
-    desc: Threshold do IntersectionObserver (0 = aparece um pouco, 1 = totalmente visível)
-    default: 0.1
-    type: Number
-  
-  root-margin:
-    desc: Margem extra ao redor do viewport para pré-carregamento
-    default: '0px'
+  direction:
+    desc: Direção do scroll e do lazy loading. Use `vertical` (padrão) para listas de rolagem vertical e `horizontal` para listas de rolagem horizontal.
     type: String
+    default: vertical
+    values: vertical | horizontal
 
   placeholder-height:
-    desc: Altura do placeholder exibido enquanto o elemento não está visível
+    desc: Altura do placeholder exibido enquanto o elemento não está visível (usado quando `direction` é `vertical`).
     default: '500px'
     type: String
 
+  placeholder-width:
+    desc: Largura do placeholder exibido enquanto o elemento não está visível (usado quando `direction` é `horizontal`).
+    default: '300px'
+    type: String
+
+  root-margin:
+    desc: Margem extra ao redor do viewport para pré-carregamento
+    default: '0px'
+    type: String
+
+  threshold:
+    desc: Threshold do IntersectionObserver (0 = aparece um pouco, 1 = totalmente visível)
+    default: 0.1
+    type: Number
+
+  visible-items:
+    desc: Expõe os índices dos itens atualmente visíveis na viewport. Útil para otimizar renders e priorizar carregamento de dados.
+    type: Array
+    default: []
+    model: true
+
 slots:
   default:
     desc: Elementos/componentes que serão carregados conforme ficam visíveis, onde cada elemento irmão dentro do slot será tratado individualmente para o lazy loading.
+
+events:
+  '@update:visible-items -> function(value)':
+    desc: Dispara toda vez que os índices dos itens visíveis são atualizados, também utilizado para v-model:visible-items.
+    params:
+      value:
+        desc: Array de índices dos itens atualmente visíveis na viewport.
+        type: Array

package/src/components/select-list-dialog/QasSelectListDialog.vue

@@ -229,7 +229,7 @@ function getDialogSlot (name) {
 
 // ------------------------- composable functions ------------------------------
 function useList () {
-  const filteredOptions = ref(props.options)
+  const filteredOptions = ref([...props.options])
 
   const selectedOptions = computed(() => {
     const options = []

package/src/components/stepper/QasStepper.vue

@@ -206,6 +206,27 @@ function previous () {
         border-radius: var(--qas-generic-border-radius);
       }
 
+      .q-stepper__tab {
+        /*
+         * Por padrão o quasar sempre deixa as demais linhas com o mesmo tamanho, exceto a primeira e a última, que são
+         * maiores devido terem alinhamento inicial e final respectivamente, enquanto as demais possuem alinhamento
+         * central. Para equalizar visualmente os tamanhos, é necessário setar uma proporção de flex diferente para a
+         * primeira/última tab e para as tabs do meio.
+         *
+         * Proporção 2:3 para equalizar visualmente os tamanhos:
+         * - Primeira/última tab: flex 2 (possuem apenas meia linha)
+         * - Tabs do meio: flex 3 (possuem linha completa dos dois lados)
+         */
+        &:first-child,
+        &:last-child {
+          flex: 2;
+        }
+
+        &:not(:first-child):not(:last-child) {
+          flex: 3;
+        }
+      }
+
       .q-stepper {
         &__tab {
           &--done {
@@ -223,9 +244,10 @@ function previous () {
               }
             }
 
-            // Seta a cor do after da linha quando a step está finalizada, é a primeira step ou a próxima é ativa.
+            // Seta a cor do after da linha quando a step está finalizada, é a primeira step ou a próxima é ativa ou finalizada.
             &:first-child,
-            &:has(+ .q-stepper__tab.q-stepper__tab--active) {
+            &:has(+ .q-stepper__tab.q-stepper__tab--active),
+            &:has(+ .q-stepper__tab.q-stepper__tab--done) {
               .q-stepper__line::after {
                  background-color: var(--q-primary);
               }

package/src/composables/use-screen.js

@@ -7,8 +7,12 @@ import { computed, reactive } from 'vue'
  *  isSmall: boolean,
  *  isMedium: boolean,
  *  isLarge: boolean,
+ *  isXLarge: boolean,
+ *  is2XLarge: boolean,
  *  untilMedium: boolean,
  *  untilLarge: boolean,
+ *  untilXLarge: boolean,
+ *  until2XLarge: boolean,
  *  isMobile: boolean
  * }}
  *
@@ -25,15 +29,27 @@ export default function () {
     // de 600 até 1023px
     isMedium: computed(() => Screen.sm),
 
-    // de 600 até 1023px
+    // Maior que 1023px
     isLarge: computed(() => Screen.gt.sm),
 
+    // Maior que 1439px
+    isXLarge: computed(() => Screen.gt.md),
+
+    // Maior que 1919px
+    is2XLarge: computed(() => Screen.gt.lg),
+
     // de 0 até 599px
     untilMedium: computed(() => Screen.lt.sm),
 
     // de 0 ate 1023px
     untilLarge: computed(() => Screen.lt.md),
 
+    // de 0 até 1439px
+    untilXLarge: computed(() => Screen.lt.lg),
+
+    // de 0 até 1919px
+    until2XLarge: computed(() => Screen.lt.xl),
+
     // Plataforma
     isMobile: computed(() => Platform.is.mobile || false)
   })

package/src/helpers/filters.js

@@ -160,7 +160,7 @@ function parseValue (value) {
   try { return JSON.parse(value) } catch { return value }
 }
 
-function booleanLabel (value, trueLabel = 'sim', falseLabel = 'não') {
+function booleanLabel (value, trueLabel = 'Sim', falseLabel = 'Não') {
   try { return JSON.parse(value) ? trueLabel : falseLabel } catch { return value }
 }
 

package/src/helpers/set-scroll-gradient.js

@@ -174,13 +174,16 @@ export default function setScrollGradient (config = {}) {
     const elementRect = element.getBoundingClientRect()
     const parentRect = element.parentElement.getBoundingClientRect()
 
+    // pequena margem para garantir que o gradiente fique grudado ao elemento.
+    const safeArea = 1
+
     /**
      * diferença entre o bottom do pai e o bottom do filho, valor positivo significa
      * que há espaço livre abaixo do filho.
      */
     const distance = {
-      end: isVertical ? (parentRect.bottom - elementRect.bottom) : (parentRect.right - elementRect.right),
-      start: isVertical ? (elementRect.top - parentRect.top) : (elementRect.left - parentRect.left)
+      end: isVertical ? (parentRect.bottom - elementRect.bottom - safeArea) : (parentRect.right - elementRect.right - safeArea),
+      start: isVertical ? (elementRect.top - parentRect.top) - safeArea : (elementRect.left - parentRect.left) - safeArea
     }
 
     span.style[getDirection(direction)] = `${distance[direction]}px`

package/src/mixins/search-filter.js

@@ -98,7 +98,7 @@ export default {
 
         this.mx_cachedOptions = []
 
-        this.mx_filterOptionsByStore('')
+        if (!this.disable) this.mx_filterOptionsByStore('')
 
         setTimeout(() => this.$emit('update:modelValue', undefined))
       }

package/src/plugins/delete/Delete.yml

@@ -3,7 +3,7 @@ type: component
 meta:
   desc: Plugin que implementa a action `destroy` do `StoreModule` adicionando comportamento de confirmação antes de excluir, este mesmo plugin é utilizado no componente `QasDelete`.
 
-inject:
+provide:
   'this.$qas.delete(config)':
     params:
       config:

package/src/plugins/dialog/Dialog.yml

@@ -3,7 +3,7 @@ type: component
 meta:
   desc: Plugin que implementa o `QasDialog`.
 
-inject:
+provide:
   'this.$qas.dialog(config)':
     params:
       config:

package/src/plugins/notify-error/NotifyError.yml

@@ -3,7 +3,7 @@ type: component
 meta:
   desc: Plugin que implementa o "QNotify" do quasar.
 
-inject:
+provide:
   'this.$qas.error(msg)':
     params:
       msg:

package/src/plugins/notify-success/NotifySuccess.yml

@@ -3,7 +3,7 @@ type: component
 meta:
   desc: Plugin que implementa o "QNotify" do quasar para notificações de sucesso.
 
-inject:
+provide:
   'this.$qas.success(msg)':
     params:
       msg:

package/src/plugins/screen/Screen.js

@@ -4,15 +4,31 @@ export default () => {
   const screensModel = {
     // até 599px
     isSmall: () => Screen.xs,
+
     // de 600 até 1023px
     isMedium: () => Screen.sm,
-    // de 600 até 1023px
+
+    // Maior que 1023px
     isLarge: () => Screen.gt.sm,
+
+    // Maior que 1439px
+    isXLarge: () => Screen.gt.md,
+
+    // Maior que 1919px
+    is2XLarge: () => Screen.gt.lg,
+
     // de 0 até 599px
     untilMedium: () => Screen.lt.sm,
+
     // de 0 ate 1023px
     untilLarge: () => Screen.lt.md,
 
+    // de 0 até 1439px
+    untilXLarge: () => Screen.lt.lg,
+
+    // de 0 até 1919px
+    until2XLarge: () => Screen.lt.xl,
+
     // Plataforma
     isMobile: () => Platform.is.mobile || false
   }

package/src/plugins/screen/Screen.yml

@@ -3,7 +3,7 @@ type: component
 meta:
   desc: Plugin que implementa o "Screen" do quasar.
 
-inject:
+provide:
   'this.$qas.screen':
     type: Object
     debugger: true
@@ -11,6 +11,10 @@ inject:
       isSmall: false
       isMedium: false
       isLarge: false
+      isXLarge: false
+      is2XLarge: false
       untilMedium: false
       untilLarge: false
+      untilXLarge: false
+      until2XLarge: false
       isMobile: false