@be-enlighten/enspace-sdk-ui

@be-enlighten/enspace-sdk-ui

Biblioteca de componentes Vue 3 do Enspace, sobre Nuxt UI 4 e Tailwind 4.

Dois tipos de componente:

• Base (dumb): só props, slots e emits. Zero data fetching, zero router.
• Entidade (wired): consomem a data layer /query do @be-enlighten/enspace-sdk-vue internamente, com override por props. As regras de domínio do Enspace (owner, membro pendente, self-exclusion) vivem no componente, não na sua app.

Navegação sempre sai por emits: a app decide a rota.

Instalação

pnpm add @be-enlighten/enspace-sdk-ui

Peers:

A app consumidora precisa do plugin @nuxt/ui/vite (Vite) ou do módulo Nuxt UI.

Setup

1. EnApp na raiz

Os componentes En* precisam do UApp do Nuxt UI na raiz (modal, tooltip, toast). O EnApp abraça o UApp por dentro e provê locale e mensagens globais, então é o único wrapper obrigatório:

<script setup lang="ts">
import { EnApp } from '@be-enlighten/enspace-sdk-ui'
</script>

<template>
  <EnApp locale="pt-BR">
    <RouterView />
  </EnApp>
</template>

locale?: MaybeRefOrGetter<EnUiLocale> (default 'pt-BR') aceita valor direto, ref ou getter. Com vue-i18n na app, a ponte é direta e não exige peer de vue-i18n no pacote:

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { locale } = useI18n()
</script>

<template>
  <EnApp :locale="locale">
    <RouterView />
  </EnApp>
</template>

O locale também é mapeado para o @nuxt/ui/locale (pt-BR → pt_br, en → en, es → es) e repassado ao UApp interno: um knob controla os textos do pacote e os do Nuxt UI.

messages?: EnUiMessagesOverrides sobrescreve textos por locale (Partial<Record<EnUiLocale, DeepPartial<EnUiMessages>>>), aplicados por deep-merge sobre o dicionário interno:

<EnApp
  :locale="locale"
  :messages="{ 'pt-BR': { members: { table: { invite: 'Convidar colegas' } } } }"
>

Resolução do locale em cada componente: prop locale → inject do EnApp → 'pt-BR'. Sem EnApp, tudo continua funcionando com o fallback. O contexto injetado é exportado (EnUiContextKey, tipo EnUiContext) para casos avançados.

toaster?: ToasterProps | null e tooltip?: TooltipProviderProps repassam a config do UApp interno (posição dos toasts, delay dos tooltips, etc). Tipagem espelha AppProps do @nuxt/ui — sem perder nada do que o UApp aceita:

<EnApp :locale="locale" :toaster="{ position: 'top-right' }" :tooltip="{ delayDuration: 200 }">
  <RouterView />
</EnApp>

2. CSS

O build extrai o CSS dos componentes (handle de resize do EnTable, regras contain de performance) para um arquivo separado, que precisa ser importado uma vez:

import '@be-enlighten/enspace-sdk-ui/style.css'

Sem esse import, a feature resizable do EnTable fica sem o handle visual e as otimizações de contain não se aplicam.

3. Registro global (opcional)

O padrão é importar por nome (import { EnMembersViewManyTable } from '@be-enlighten/enspace-sdk-ui'). Para registro global:

import { EnspaceUi } from '@be-enlighten/enspace-sdk-ui'
import '@be-enlighten/enspace-sdk-ui/style.css'

app.use(EnspaceUi, { locale: 'pt-BR' }) // opções: `locale` e `messages`, mesma semântica das props do EnApp

O plugin registra todos os componentes públicos, provê o contexto de i18n no nível da app e chama o shim de NuxtLink. Ele não abraça o UApp: o <EnApp> na raiz continua necessário.

installNuxtLinkShim(app) — componentes do Nuxt UI com to (ULink, UButton) renderizam <NuxtLink custom>, que só o Nuxt registra. Em apps Vite + vue-router, o shim registra um NuxtLink que delega ao RouterLink com o mesmo contrato de slot (href, navigate, isActive). É no-op sem vue-router ou quando NuxtLink já existe. O plugin EnspaceUi chama o shim automaticamente; com imports nomeados, chame manualmente.

4. Nuxt 4

export default defineNuxtConfig({
  modules: [
    '@be-enlighten/enspace-sdk-vue/nuxt', // data layer, necessário para os componentes de entidade
    '@be-enlighten/enspace-sdk-ui/nuxt',
  ],
})

O módulo auto-importa todos os componentes e injeta o CSS. Opções na chave enspaceUi:

O <EnApp> na raiz continua necessário no Nuxt.

5. Base-only (sem o grafo de AI)

O barrel raiz re-exporta estaticamente todos os componentes — inclusive os de AI, cujo grafo de deps toca as peers opcionais CJS (ai, streamdown-vue). Em apps que usam só os componentes base, isso pode quebrar o dev do Vite (os CJS profundos são servidos sem interop CJS→ESM).

Para esses apps existe o entry @be-enlighten/enspace-sdk-ui/base com os quatro componentes base (EnApp, EnLayout, EnTable, EnKanbanBoard) e seus tipos — o grafo de AI nunca é importado e as peers opcionais de AI não são necessárias:

import { EnApp, EnTable, type EnTableColumn } from '@be-enlighten/enspace-sdk-ui/base'
import '@be-enlighten/enspace-sdk-ui/style.css'

Apps Nuxt que usam só os componentes base não precisam fazer nada: o módulo /nuxt já registra os quatro base pelo entry ./base (os demais continuam vindo do barrel).

Componentes

Todo componente com texto embutido aceita a prop locale ('pt-BR' | 'en' | 'es') como override pontual. Na prática o locale vem do <EnApp>; a prop só é necessária para um componente divergir do resto da app.

EnTable

Motor: UTable + @tanstack/vue-table. A API pública não expõe tipos da lib de tabela.

• Colunas declarativas (EnTableColumn): { key, label, sortable?, align?, hidden? }.
• Seleção em massa: selectable + v-model:selected (array de linhas, por referência de objeto). Checkbox no header com estado indeterminado; a seleção é podada quando rows muda.
• Ordenação controlada: coluna sortable renderiza botão no header, o estado vem pela prop sort e as mudanças saem por sort-change. Quem ordena é o consumer ou o backend.
• Paginação server-side: prop pagination: { page, pageCount, total? } + page-change, ou override completo pelo slot #pagination.
• Resize, visibilidade, ordem e virtualização, todos opt-in: resizable (handle visual + update:columnSizing), columnSizing (larguras controladas, fecha o round-trip de persistência), columnVisibility + update:columnVisibility, columnOrder + update:columnOrder (as colunas estruturais select/actions não se movem), virtualize (padrão 44/10 quando ligado).
• Estados: loading (spinner + aria-busy) e vazio via UEmpty interno (emptyState ou slot #empty).
• A11y: tabela semântica, aria-sort, aria-label nos checkboxes, linhas com foco e teclado (Enter/Espaço) quando há listener de row-click.

Componentes de entidade

• Regras de domínio implementadas: owner nunca é oferecido como opção de role (convite e troca) e não pode ser modificado nem removido (o menu vira botão desabilitado com tooltip); membro pending não muda de status nem de role; self-exclusion é detectada (remover o próprio usuário fica desabilitado); remoção sempre atrás de modal de confirmação.
• Erro não é vazio: componentes wired renderizam estado de erro próprio (ícone, título, descrição e botão de retry). Falha de API nunca cai no empty state.
• Override controlado: passar a prop de dados (ex.: members) desabilita a query interna, sem fetch desnecessário.
• Família inbox (EnNotificationsView* + EnNotificationsActions*): o EnNotificationsViewInbox monta lista, leitura e slideover mobile, e delega aos cards de ação pelo type.key da notificação. A busca é server-side com debounce de 300ms. Deep-link é da app: a prop open-reference seleciona a notificação e open-reference-resolved avisa para limpar a URL.
• Família communications (EnCommunications*): EnCommunicationsViewOneThread liga /query (useThread/useThreadMessages/mutations) e /realtime (useLiveThread + useTypingIndicator no mesmo canal) — mensagens recebidas chegam por invalidação de cache e "está digitando…" via relay efêmero; chat de campo (entity + entityReference + fieldId) dispara useEnsureThread (obter-ou-criar) automático no mount. Thread closed/archived não aceita mensagem (o composer vira aviso e o kebab oferece reabrir). EnCommunicationsViewManyThreads não assina canal próprio (não existe canal de lista no gateway): a frescura vem da invalidação do Pinia Colada feita pelo detalhe e pelas mutations. EnCommunicationsViewManyComments resolve o threading de dois níveis client-side (a lista da API é plana) e restringe editar/excluir ao próprio comentário (join pelo user do profile); sem canal de lista de threads, exclusão sempre atrás de modal de confirmação.
• SSR-safe: nenhum acesso a window/document fora de guards.

i18n

Dicionário interno pt-BR/en/es com fallback (match exato → prefixo de língua → pt-BR), sem peer de vue-i18n. O locale global vem do <EnApp>; componentes também aceitam a prop locale como override pontual. Todo texto pode ser sobrescrito globalmente pela prop messages do EnApp (deep-merge por locale) ou pontualmente por props e slots (ex.: emptyState.title).

import { resolveMessages } from '@be-enlighten/enspace-sdk-ui'

resolveMessages('es').table.emptyTitle // 'Sin resultados'

Nomes dos componentes

En{Entidade}{Grupo}{Cardinalidade?}{Variante}

• Entidade: domínio do recurso (Members, Workspaces, Account, Notifications, ...).
• Grupo: View, Forms ou Shared.
• Cardinalidade: Many ou One, obrigatória em View e ausente fora dele.
• Variante (opcional): Table, Selector, Bell, Slideover, ...
• Bases: En{Nome} simples (EnTable, EnApp, EnLayout), sempre dumb.

Exemplos: EnMembersViewManyTable, EnWorkspacesSharedSelector, EnAccountSharedMenu, EnNotificationsSharedBell.

Licença

MIT.