@data-fair/lib-vue

@data-fair/lib-vue

Composables and utilities for Vue 3 applications of the data-fair stack (services UIs, data-fair applications…): session, data fetching, URL state, websockets, UI notifications.

Install

npm i @data-fair/lib-vue

Peer dependencies: vue 3 and ofetch 1. Optional peers, needed only by the modules that use them:

Modules

Import each module by its path, with the .js extension.

reactive-search-params-global.js and locale-dayjs-global.js are module-level singletons kept for older non-SSR apps; prefer the plugins below.

Setup

Session, search params, ui-notif and locale-dayjs are Vue plugins: create them once in main.ts, then use the matching composable in components.

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createSession } from '@data-fair/lib-vue/session.js'
import { createReactiveSearchParams } from '@data-fair/lib-vue/reactive-search-params.js'
import { createUiNotif } from '@data-fair/lib-vue/ui-notif.js'
import { createLocaleDayjs } from '@data-fair/lib-vue/locale-dayjs.js'

(async function () {
  const router = createRouter({ history: createWebHistory('/my-service/'), routes })
  const session = await createSession({ directoryUrl: '/simple-directory', siteInfo: true })

  createApp(App)
    .use(router)
    .use(createReactiveSearchParams(router))
    .use(session)
    .use(createUiNotif())
    .use(createLocaleDayjs(session.state.lang))
    .mount('#app')
})()

siteInfo: true loads the site colors and themes, required by vuetifySessionOptions of @data-fair/lib-vuetify.

Session

import { useSession, useSessionAuthenticated } from '@data-fair/lib-vue/session.js'

const session = useSession()
session.user.value // undefined when anonymous
session.account.value // active account (user or organization, with optional department)
session.login()

// in a page that requires a logged in user (throws otherwise)
const { user, account, accountRole } = useSessionAuthenticated()

Roles, admin mode and organization switching are covered by the data-fair-session skill.

Fetch and actions

import { computed } from 'vue'
import { ofetch } from 'ofetch'
import { useFetch } from '@data-fair/lib-vue/fetch.js'
import { useAsyncAction } from '@data-fair/lib-vue/async-action.js'

const params = computed(() => ({ size: 20, q: search.value }))
const items = useFetch<{ results: Item[] }>('/my-service/api/items', { query: params })
// items.data, items.loading, items.error, items.refresh()

const remove = useAsyncAction(async (id: string) => {
  await ofetch(`/my-service/api/items/${id}`, { method: 'DELETE' })
  await items.refresh()
}, { success: 'Item deleted' })
// remove.execute(id), remove.loading

useFetch options: query, watch (default true), immediate (default true), waitFor (no request while it is false), notifError (default true).

Search params

import { useReactiveSearchParams, useStringSearchParam, useBooleanSearchParam } from '@data-fair/lib-vue/reactive-search-params.js'

const searchParams = useReactiveSearchParams() // Record<string, string>, synced with the URL
const q = useStringSearchParam('q') // computed ref, the param is removed when it equals the default
const showAll = useBooleanSearchParam('all') // stored as '1' / '0'

Websockets

import { useWS } from '@data-fair/lib-vue/ws.js'

// one socket per path, shared by all callers; the subscription ends with the component scope
useWS('/my-service/api/')?.subscribe<Notification>(`user:${userId}:notifications`, (notification) => {
  notifications.value.unshift(notification)
})

Server side and channel permissions: data-fair-ws skill.

Owners with a deleted department

A department deleted in simple-directory keeps its id on the resources it owned but loses its departmentName. useDisplayOwner builds the label in the session language: Ancien département (<id>) / Former department (<id>).

import { useDisplayOwner } from '@data-fair/lib-vue/owner.js'

const { departmentLabel, displayOwner } = useDisplayOwner()
departmentLabel(owner.department, owner.departmentName) // "Direction" | "Former department (head)" | undefined
displayOwner(owner) // same owner, with departmentName filled when the department was deleted

@data-fair/lib-vuetify/owner-avatar.vue applies it itself: pass it the raw owner. Use departmentLabel for text labels and displayOwner only for a component that reads departmentName directly. Outside a component, use the pure formatDepartmentLabel(lang, department, departmentName).

Data-fair applications

For applications (visualizations embedded by data-fair: window.APPLICATION, config schema, filters convention, selection), see the data-fair-app skill.