@bildvitta/quasar-ui-asteroid 3.20.0-beta.2 → 3.20.0-beta.21

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

@@ -0,0 +1,262 @@
+<template>
+  <!--
+    Itera sobre todos os componentes extraídos do slot
+    Cada item pode estar em dois estados:
+    1. Visível: Renderiza o componente real
+    2. Não visível: Renderiza placeholder vazio (reserva espaço)
+  -->
+  <template
+    v-for="(item, index) in items"
+    :key="index"
+  >
+    <transition enter-active-class="animated fadeIn slow">
+      <!-- Componente real - renderizado quando visível -->
+      <component
+        :is="item"
+        v-if="visibleItems.has(index)"
+      />
+
+      <!-- Placeholder - div vazia que reserva espaço no layout -->
+      <div
+        v-else
+        :ref="element => setPlaceholderRef(element, index)"
+      />
+    </transition>
+  </template>
+</template>
+
+<script setup>
+import { ref, onMounted, onBeforeUnmount, useSlots, nextTick, watch } from 'vue'
+
+defineOptions({ name: 'QasLazyLoadingComponents' })
+
+const props = defineProps({
+  threshold: {
+    type: Number,
+    default: 0.1 // 10% visível
+  },
+
+  rootMargin: {
+    type: String,
+    default: '0px'
+  },
+
+  direction: {
+    type: String,
+    default: 'vertical',
+    validator: value => ['vertical', 'horizontal'].includes(value)
+  },
+
+  placeholderHeight: {
+    type: String,
+    default: '500px'
+  },
+
+  placeholderWidth: {
+    type: String,
+    default: '300px'
+  }
+})
+
+// models
+const visibleItemsModel = defineModel('visibleItems', { type: Array, default: () => [] })
+
+// refs
+/**
+ * Lista de VNodes extraídos do slot default
+ * Cada item é um VNode que representa um componente filho
+ *
+ * Exemplo:
+ * <qas-lazy-loading-components>
+ *   <ComponenteA /> <- items[0]
+ *   <ComponenteB /> <- items[1]
+ * </qas-lazy-loading-components>
+ */
+const items = ref([])
+
+/**
+ * Set de índices dos componentes que já foram renderizados
+ * Quando um placeholder entra no viewport, seu índice é adicionado aqui
+ * @type {Ref<Set<number>>}
+ */
+const visibleItems = ref(new Set())
+
+// composables
+const slots = useSlots()
+
+// consts
+/**
+ * Map que armazena referências aos elementos placeholder
+ * Chave: índice do componente
+ * Valor: elemento DOM do placeholder
+ * @type {Map<number, HTMLElement>}
+ */
+const placeholderRefs = new Map()
+
+/**
+ * Instância do IntersectionObserver
+ * Responsável por detectar quando placeholders entram no viewport
+ * @type {IntersectionObserver | null}
+ */
+let observer = null
+
+// lifecycle hooks
+onMounted(handleObserver)
+
+// Observa mudanças no slot para atualizar items
+watch(
+  () => slots.default?.(),
+  handleObserver,
+  { flush: 'post' }
+)
+
+onBeforeUnmount(() => {
+  if (!observer) return
+
+  // Limpa o observer para evitar memory leaks
+  observer.disconnect()
+})
+
+// functions
+/**
+ * Cria e configura o IntersectionObserver
+ * Observa todos os placeholders e renderiza componentes quando visíveis
+ *
+ * Fluxo:
+ * 1. Cria observer com threshold e rootMargin configurados
+ * 2. Quando placeholder entra no viewport:
+ *    - Encontra o índice correspondente no Map
+ *    - Adiciona índice ao visibleItems (renderiza componente)
+ *    - Para de observar esse elemento
+ * 3. Observa todos os placeholders armazenados no Map
+ */
+function createObserver () {
+  observer = new IntersectionObserver(
+    entries => {
+      entries.forEach(entry => {
+        if (!entry.isIntersecting) return
+
+        // Converte Map em Array para facilitar busca
+        const list = Array.from(placeholderRefs.entries())
+
+        // Encontra o índice do placeholder no Map
+        const index = list.findIndex(([_, element]) => element === entry.target)
+
+        // Verifica se encontrou o índice (index !== -1)
+        if (!~index) return
+
+        // Adiciona ao Set para renderizar o componente real
+        visibleItems.value.add(index)
+
+        // Para de observar - componente já foi renderizado
+        observer.unobserve(entry.target)
+
+        // Emite os índices atualmente visíveis
+        visibleItemsModel.value = Array.from(visibleItems.value)
+      })
+    },
+    {
+      threshold: props.threshold,
+      rootMargin: props.rootMargin
+    }
+  )
+
+  // Observa todos os placeholders do Map
+  placeholderRefs.forEach(element => {
+    observer.observe(element)
+  })
+}
+
+function handleObserver () {
+  setItems()
+
+  // Reconstrói o observer com os novos items
+  if (observer) {
+    observer.disconnect()
+  }
+
+  nextTick(() => requestAnimationFrame(createObserver))
+}
+
+/**
+ * Extrai e achata os VNodes do slot default
+ * Suporta múltiplos cenários:
+ * - Componentes individuais: <ComponenteA /> <ComponenteB />
+ * - v-for: <Component v-for="..." />
+ * - template v-for: <template v-for="..."><Component /></template>
+ *
+ * @param {Array} vnodes - Array de VNodes
+ * @returns {Array} Array de VNodes achatado
+ */
+function flattenVNodes (vnodes) {
+  const flattened = []
+
+  vnodes.forEach(vnode => {
+    // Ignora VNodes inválidos (null, undefined, primitivos)
+    if (!vnode || typeof vnode !== 'object') return
+
+    /**
+     * Se for um Fragment (v-for, template, v-if, etc), achata recursivamente os children
+     * Fragments são wrappers que o Vue cria para agrupar múltiplos elementos
+     */
+    const isFragment = typeof vnode.type === 'symbol' && Array.isArray(vnode.children)
+
+    if (isFragment) {
+      flattened.push(...flattenVNodes(vnode.children))
+    } else {
+      // VNode normal (componente ou elemento HTML)
+      flattened.push(vnode)
+    }
+  })
+
+  return flattened
+}
+
+/**
+ * Extrai os VNodes do slot default e armazena em items
+ * Achata automaticamente fragments e v-for
+ *
+ * Exemplo de uso:
+ * <qas-lazy-loading-components>
+ *   <ComponenteA />  <- vnode 0
+ *   <ComponenteB />  <- vnode 1
+ *   <Component v-for="item in 10" /> <- vnode 2-11
+ * </qas-lazy-loading-components>
+ */
+function setItems () {
+  const slotContent = slots.default?.() || []
+  const flattenedItems = flattenVNodes(slotContent)
+
+  items.value = flattenedItems
+}
+
+/**
+ * Armazena referência do elemento placeholder no Map
+ * Chamado automaticamente pelo Vue através do :ref no template
+ *
+ * @param {HTMLElement | null} element - Elemento DOM do placeholder
+ * @param {number} index - Índice do componente
+ */
+function setPlaceholderRef (element, index) {
+  if (!element) return
+
+  placeholderRefs.set(index, element)
+
+  const itemProps = items.value[index].props
+
+  if (props.direction === 'horizontal') {
+    /**
+     * Define a largura do placeholder com base no atributo "data-placeholder-width" caso queira customizar
+     * para o elemento específico, e não o definido na prop placeholderWidth.
+     */
+    element.style.width = itemProps?.['data-placeholder-width'] || props.placeholderWidth
+    element.style.flexShrink = '0'
+  } else {
+    /**
+     * Define a altura do placeholder com base no atributo "data-placeholder-height" caso queira customizar
+     * para o elemento específico, e não o definido na prop placeholderHeight.
+     */
+    element.style.height = itemProps?.['data-placeholder-height'] || props.placeholderHeight
+  }
+}
+</script>

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

@@ -0,0 +1,49 @@
+type: component
+
+meta:
+  desc: Componente para carregar elementos do slot somente quando ficam visíveis na viewport, otimizando performance da página.
+
+props:
+  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 (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/list-view/QasListView.vue

@@ -13,7 +13,7 @@
         <div v-if="showResults">
           <slot />
 
-          <q-inner-loading :showing="mx_isFetching">
+          <q-inner-loading :showing="mx_isFetching && useLoading">
             <q-spinner color="grey" size="3em" />
           </q-inner-loading>
         </div>
@@ -108,6 +108,11 @@ export default {
       type: Boolean
     },
 
+    useLoading: {
+      type: Boolean,
+      default: true
+    },
+
     usePagination: {
       default: true,
       type: Boolean
@@ -129,6 +134,7 @@ export default {
   },
 
   emits: [
+    'fetch-start',
     'fetch-success',
     'fetch-error',
     'update:errors',
@@ -158,7 +164,7 @@ export default {
      * automaticamente.
      */
     hasDeleteEventListener () {
-      return this.useAutoHandleOnDelete || this.useAutoRefetchOnDelete || (!this.useStore && this.entity)
+      return this.useAutoHandleOnDelete || this.useAutoRefetchOnDelete
     },
 
     hasHeaderSlot () {
@@ -189,7 +195,7 @@ export default {
     },
 
     showResults () {
-      return this.hasResults || this.useResultsAreaOnly
+      return this.hasResults || this.useResultsAreaOnly || !this.useLoading
     },
 
     paginationClasses () {
@@ -251,6 +257,8 @@ export default {
           ...externalPayload
         }
 
+        this.$emit('fetch-start', payload)
+
         const response = await this.handleFetchList(payload)
 
         const { errors, fields, metadata, results, count } = response.data
@@ -374,7 +382,7 @@ export default {
     },
 
     onDeleteResult (event) {
-      if (this.useAutoRefetchOnDelete || !this.useStore) {
+      if (this.useAutoRefetchOnDelete) {
         this.mx_fetchHandler({ ...this.mx_context, url: this.url }, this.fetchList)
         return
       }

package/src/components/list-view/QasListView.yml

@@ -86,6 +86,11 @@ props:
     default: true
     type: Boolean
 
+  use-loading:
+    desc: Controla se o componente vai exibir um loading quando estiver fazendo fetch dos dados.
+    default: true
+    type: Boolean
+
   use-pagination:
     desc: Controla se vai ter ou não paginação.
     default: true
@@ -125,6 +130,13 @@ slots:
     desc: 'Slot para acessar o header.'
 
 events:
+  '@fetch-start -> function(value)':
+    desc: Dispara logo antes da action "fetchList".
+    params:
+      value:
+        desc: Retorna o payload enviado para o fetchList, contendo paginação, filtros, search, etc.
+        type: Object
+
   '@fetch-success -> function(value)':
     desc: Dispara quando a action "fetchList" é executada com sucesso.
     params:

package/src/components/page-header/QasPageHeader.vue

@@ -3,13 +3,23 @@
     <q-toolbar class="justify-between q-mb-md q-px-none qas-page-header">
       <div class="ellipsis">
         <q-toolbar-title v-if="props.title" class="text-h3">
-          {{ props.title }}
+          <qas-skeleton v-if="props.skeleton" max-width="300px" type="text" use-contrast />
+
+          <template v-else>
+            {{ props.title }}
+          </template>
         </q-toolbar-title>
 
         <q-breadcrumbs v-if="hasBreadcrumbs" class="text-caption" gutter="xs" separator-color="grey-8">
           <q-breadcrumbs-el v-if="props.useHomeIcon" class="qas-page-header__breadcrumbs-el text-grey-8" icon="sym_r_home" :to="homeRoute" />
 
-          <q-breadcrumbs-el v-for="(item, index) in normalizedBreadcrumbs" :key="index" class="ellipsis inline-block qas-page-header__breadcrumbs-el" :label="item.label" :to="item.route" />
+          <q-breadcrumbs-el v-for="(item, index) in normalizedBreadcrumbs" :key="index" class="ellipsis inline-block qas-page-header__breadcrumbs-el" tag="div" :to="item.route">
+            <qas-skeleton v-if="props.skeleton" v-bind="getBreadcrumbSkeletonProps(item)" />
+
+            <template v-else>
+              {{ item.label }}
+            </template>
+          </q-breadcrumbs-el>
         </q-breadcrumbs>
       </div>
 
@@ -25,6 +35,7 @@
 </template>
 
 <script setup>
+import QasSkeleton from '../skeleton/QasSkeleton.vue'
 import QasHeader from '../header/QasHeader.vue'
 
 import { useOverlayNavigation } from '../../composables'
@@ -52,6 +63,10 @@ const props = defineProps({
     type: [Object, String]
   },
 
+  skeleton: {
+    type: Boolean
+  },
+
   title: {
     default: '',
     type: String
@@ -77,6 +92,7 @@ useMeta(() => ({ title: props.title }))
 
 // computed
 const hasBreadcrumbs = computed(() => props.useBreadcrumbs && !isOverlay)
+
 const transformedBreadcrumbs = computed(() => {
   const list = [...castArray(props.breadcrumbs || props.title)]
 
@@ -95,7 +111,7 @@ const transformedBreadcrumbs = computed(() => {
   })
 })
 
-const normalizedBreadcrumbs = computed(() => {
+const truncatedBreadcrumbs = computed(() => {
   const breadcrumbsSize = transformedBreadcrumbs.value.length
 
   if (breadcrumbsSize < 5) return transformedBreadcrumbs.value
@@ -116,9 +132,39 @@ const normalizedBreadcrumbs = computed(() => {
   ]
 })
 
+/**
+ * Caso a prop skeleton esteja ativa, retorna um array com 3 elementos vazios para renderizar
+ * os esqueletos dos breadcrumbs. Caso contrário, retorna os breadcrumbs truncados.
+ */
+const normalizedBreadcrumbs = computed(() => {
+  if (props.skeleton) {
+    return Array.from({ length: 3 }).map(() => ({ label: '', route: null }))
+  }
+
+  return truncatedBreadcrumbs.value
+})
+
 const hasHeader = computed(() => !!Object.keys(props.headerProps).length)
 
 const homeRoute = computed(() => router.hasRoute('Root') ? { name: 'Root' } : '/')
+
+// functions
+/**
+ * Retorna propriedades para o componente QasSkeleton usado nos breadcrumbs
+ */
+function getBreadcrumbSkeletonProps () {
+  const min = 60
+  const max = 160
+
+  // Gera uma largura aleatória entre min e max entre 60 e 160 pixels
+  const width = Math.floor(Math.random() * (max - min + 1)) + min
+
+  return {
+    type: 'text',
+    useContrast: true,
+    width: `${width}px`
+  }
+}
 </script>
 
 <style lang="scss">

package/src/components/page-header/QasPageHeader.yml

@@ -24,6 +24,11 @@ props:
     desc: Rota raiz do breadcrumbs.
     type: [Object, String]
 
+  skeleton:
+    desc: Exibe um esqueleto de carregamento no lugar do conteúdo.
+    default: false
+    type: Boolean
+
   use-breadcrumbs:
     desc: Habilita ou não o breadcrumbs.
     default: true

package/src/components/router-link/QasRouterLink.vue

@@ -0,0 +1,72 @@
+<!--
+  Tratamento feito para ter o comportamento de ao abrir em uma nova guia, direto na página, abre sem overlay.
+  Caso contrário, ao clicar normalmente, abrirá no overlay.
+-->
+<template>
+  <router-link
+    class="qas-router-link text-no-decoration"
+    v-bind="routerLinkProps"
+  >
+    <slot>
+      {{ props.label }}
+    </slot>
+  </router-link>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { useRouter } from 'vue-router'
+import { useOverlayNavigation } from 'asteroid'
+
+defineOptions({ name: 'QasRouterLink' })
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ''
+  },
+
+  route: {
+    type: Object,
+    required: true
+  },
+
+  useOverlayRoute: {
+    type: Boolean
+  }
+})
+
+// composables
+const router = useRouter()
+const { getOverlayRoute } = useOverlayNavigation()
+
+// computeds
+const routerLinkProps = computed(() => {
+  return {
+    to: props.route,
+
+    ...(props.useOverlayRoute && {
+      onClick: event => {
+        /**
+         * @click.prevent pra evitar com que o router-link já trate o clique e tente navegar para a rota
+         * normalmente, o que não é o desejado quando queremos abrir um overlay
+         */
+        event.preventDefault()
+
+        router.push(getOverlayRoute(props.route))
+      }
+    })
+  }
+})
+</script>
+
+<style lang="scss">
+.qas-router-link {
+  transition: color var(--qas-generic-transition);
+  color: inherit;
+
+  &:hover {
+    color: $primary;
+  }
+}
+</style>

package/src/components/router-link/QasRouterLink.yml

@@ -0,0 +1,24 @@
+type: component
+
+meta:
+  desc: Componente de link baseado no router-link. Ao passar a prop use-overlay-route, o clique normal abre a rota no overlay. Ao abrir em uma nova guia, navega diretamente para a página, sem overlay.
+
+props:
+  label:
+    desc: Texto exibido como conteúdo padrão do link, utilizado quando o slot default não é fornecido.
+    default: ''
+    type: String
+
+  route:
+    desc: Rota de destino do link, repassada diretamente ao `router-link`.
+    required: true
+    type: Object
+
+  use-overlay-route:
+    desc: Quando verdadeiro, o clique no link abre a rota no overlay em vez de navegar normalmente. Ao abrir em uma nova guia, o comportamento padrão do `router-link` é mantido.
+    default: false
+    type: Boolean
+
+slots:
+  default:
+    desc: Conteúdo do link. Quando não fornecido, exibe o valor da prop `label`.

package/src/components/search-box/QasSearchBox.vue

@@ -138,7 +138,7 @@ export default {
     },
 
     hasNoOptionsOnFirstFetch () {
-      return this.mx_fetchCount === 1 && !this.mx_hasFilteredOptions
+      return this.mx_fetchCount === 1 && !this.mx_hasFilteredOptions && !this.mx_hasNextPage
     },
 
     containerHeight () {

package/src/components/select/QasSelect.vue

@@ -1,5 +1,5 @@
 <template>
-  <q-select v-model="model" v-bind="attributes" class="qas-select" :class="componentClasses" no-error-icon>
+  <q-select ref="select" v-model="model" v-bind="attributes" class="qas-select" :class="componentClasses" no-error-icon>
     <template v-if="hasIcon" #prepend>
       <q-icon :name="defaultIcon" />
     </template>
@@ -409,6 +409,13 @@ export default {
 
     onPopupHide () {
       this.isPopupContentOpen = false
+
+      /**
+       * necessário limpar o campo de input de pesquisa ao fechar o popup, para evitar que o valor da busca permaneça
+       * no campo quando abrir novamente e também o texto não sobreponha os itens selecionados ao apertar a tecla tab.
+       */
+      if (this.isSearchable) this.$refs.select.updateInputValue('', true)
+
       this.$emit('popup-hide')
     },