@kinetis/vector-ui 0.0.0-stage → 0.9.1

package/app/composables/useVectorForm.ts

@@ -0,0 +1,36 @@
+import type { VectorField } from '#vector/app/types/vector'
+
+/** The value a fresh input holds: the field's default, or the type's empty value. */
+export function initialValue(field: VectorField): unknown {
+    if (field.hasDefault) return field.default
+    if (field.type === 'boolean') return false
+    if (field.type === 'manyToMany') return []
+    return null
+}
+
+/**
+ * Maps the framework's 422 document onto field names; returns the
+ * message that names no field, if any.
+ */
+export function applyViolations(error: unknown, values: Record<string, unknown>, serverErrors: Record<string, string[]>): string | null {
+    const failure = error as { status?: number, statusCode?: number, data?: { errors?: unknown } } | null
+    const violations = failure?.data?.errors
+
+    if ((failure?.status ?? failure?.statusCode) !== 422 || !Array.isArray(violations)) {
+        return vectorErrorMessage(error)
+    }
+
+    let general: string | null = null
+
+    for (const violation of violations as { path: (string | number)[], message: string }[]) {
+        const key = String(violation.path[0] ?? '')
+
+        if (key && key in values) {
+            (serverErrors[key] ??= []).push(`${violation.message.charAt(0).toUpperCase()}${violation.message.slice(1)}`)
+        } else {
+            general = violation.message
+        }
+    }
+
+    return general ?? (Object.keys(serverErrors).length === 0 ? vt('common.serverRejected') : null)
+}

package/app/composables/useVectorIdle.ts

@@ -0,0 +1,39 @@
+import { useEventListener, useIdle } from '@vueuse/core'
+
+/**
+ * Ends the session when nobody has used the admin for a while. The
+ * session otherwise never ends on its own: the store renews the token
+ * before it runs out and the shell polls badges and the inbox, so an open
+ * tab stays signed in for as long as it is open. This watches for a real
+ * person — a pointer, a key, a touch, a scroll — and, once app config
+ * `vector.idleMinutes` have passed without one, calls `onIdle` exactly
+ * once. A tab that comes back into view after sleeping is checked at
+ * that moment too, since a timer may not have fired meanwhile.
+ * `idleMinutes: 0` turns it off. Call it from the signed-in layout.
+ */
+export function useVectorIdle(onIdle: () => void | Promise<void>): void {
+    const minutes = useAppConfig().vector.idleMinutes
+
+    if (!import.meta.client || !(minutes > 0)) return
+
+    const timeout = minutes * 60_000
+    const { idle, lastActive, reset } = useIdle(timeout, { listenForVisibilityChange: false })
+    let fired = false
+
+    const fire = () => {
+        if (fired) return
+        fired = true
+        void onIdle()
+    }
+
+    // synchronous: the session ends the moment the wait is over, not on a render tick
+    watch(idle, (now) => {
+        if (now) fire()
+    }, { flush: 'sync' })
+
+    useEventListener(document, 'visibilitychange', () => {
+        if (document.visibilityState !== 'visible') return
+        if (Date.now() - lastActive.value >= timeout) fire()
+        else reset()
+    })
+}

package/app/composables/useVectorImpersonation.ts

@@ -0,0 +1,78 @@
+/**
+ * Impersonation from the UI. Bearer mode receives a new token and swaps
+ * it in the auth store; cookie mode is told to reload, the session
+ * having been swapped by the application.
+ */
+export function useVectorImpersonation() {
+    const api = useVectorApi()
+    const auth = useVectorAuthStore()
+    const runtime = useVectorRuntime()
+    const { load } = useVectorSchema()
+    const impersonator = useState<{ id: number | string, name: string | null } | null>('vector.impersonator', () => null)
+
+    type Swap = { accessToken?: string, expiresIn?: number, user?: { id: number | string, name: string }, target?: { id: number | string, name: string }, reload?: boolean }
+
+    async function apply(result: Swap) {
+        if (result.reload && import.meta.client) {
+            window.location.reload()
+
+            return
+        }
+
+        if (!result.accessToken) {
+            throw new Error(vt('shell.impersonation.noToken'))
+        }
+
+        // who the token is for: the application's `user`, the controller's `target`, or the token's own subject
+        const subject = result.user ?? result.target ?? { id: subjectOf(result.accessToken) ?? '', name: auth.user?.name ?? '' }
+
+        {
+            const previous = { token: auth.token, expiresAt: auth.expiresAt, user: auth.user }
+            auth.adopt(result.accessToken, result.expiresIn ?? 3600, { id: subject.id, name: subject.name })
+            useVectorPreferences().clear()
+
+            try {
+                await load(true)
+            } catch (error) {
+                // the target cannot use the admin at all: undo the swap on both sides and say so
+                const status = (error as { status?: number, statusCode?: number } | null)?.status ?? (error as { statusCode?: number } | null)?.statusCode
+
+                if (status === 403) {
+                    await api('/vector/impersonate', { method: 'DELETE' }).catch(() => undefined)
+                    if (previous.token && previous.user) auth.adopt(previous.token, Math.max(1, Math.round((previous.expiresAt - Date.now()) / 1000)), previous.user)
+                    await load(true)
+                    throw new Error(vt('shell.impersonation.noAccess', { name: subject.name }), { cause: error })
+                }
+
+                throw error
+            }
+        }
+    }
+
+    /** The `sub` of a JWT, read without verifying it: the server already did, and this only labels the session. */
+    function subjectOf(token: string): string | null {
+        try {
+            const payload = JSON.parse(atob(token.split('.')[1]?.replace(/-/g, '+').replace(/_/g, '/') ?? '')) as { sub?: unknown }
+
+            return typeof payload.sub === 'string' || typeof payload.sub === 'number' ? String(payload.sub) : null
+        } catch {
+            return null
+        }
+    }
+
+    async function start(userId: number | string) {
+        await apply(await api<Swap>(`/vector/impersonate/${encodeURIComponent(String(userId))}`, { method: 'POST' }))
+    }
+
+    async function stop() {
+        await apply(await api<Swap>('/vector/impersonate', { method: 'DELETE' }))
+    }
+
+    /** Reads who is impersonating from /vector/me; null when nobody. */
+    async function refresh() {
+        const me = await api<{ impersonator: number | string | null }>('/vector/me')
+        impersonator.value = me.impersonator === null ? null : { id: me.impersonator, name: runtime.user && 'impersonatorName' in runtime.user ? String((runtime.user as { impersonatorName?: string }).impersonatorName ?? '') : null }
+    }
+
+    return { impersonator, start, stop, refresh }
+}

package/app/composables/useVectorInputs.ts

@@ -0,0 +1,61 @@
+import type { Component } from 'vue'
+import type { VectorField } from '#vector/app/types/vector'
+
+/**
+ * The input side of the field registry: the component that edits a
+ * field in a form. Built-ins are imported explicitly, like the cells;
+ * `app.config.vector.inputs` names globally registered overrides.
+ */
+const inputs: Record<string, Component> = {
+    string: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Text.vue')),
+    email: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Text.vue')),
+    url: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Text.vue')),
+    slug: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Text.vue')),
+    password: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Text.vue')),
+    color: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Text.vue')),
+    file: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Upload.vue')),
+    image: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Upload.vue')),
+    text: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Textarea.vue')),
+    markdown: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Markdown.vue')),
+    richtext: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/RichText.vue')),
+    json: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Textarea.vue')),
+    keyValue: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/KeyValue.vue')),
+    number: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Number.vue')),
+    money: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Money.vue')),
+    boolean: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Boolean.vue')),
+    enum: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Enum.vue')),
+    currency: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Currency.vue')),
+    date: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/DateTime.vue')),
+    datetime: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/DateTime.vue')),
+    belongsTo: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Relation.vue')),
+    manyToMany: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Relation.vue')),
+    hasMany: defineAsyncComponent(() => import('#vector/app/components/Vx/Input/Repeater.vue')),
+}
+
+export function useVectorInputs() {
+    const appConfig = useAppConfig()
+
+    function inputFor(field: VectorField): Component | string {
+        const overrides = appConfig.vector.inputs
+
+        if (field.component && overrides[field.component]) {
+            return overrides[field.component]!
+        }
+
+        const runtime = useVectorExtensions().inputs
+
+        if (field.component && runtime.has(field.component)) {
+            return runtime.get(field.component)!
+        }
+
+        return overrides[field.type] ?? inputs[field.type] ?? inputs.string!
+    }
+
+    /** Whether a field is edited in this operation at all. */
+    function editable(field: VectorField, operation: 'create' | 'update'): boolean {
+        if (field.type === 'hasMany') return !!field.repeater && field.views.includes(operation)
+        return !field.readonly && field.views.includes(operation) && !['id', 'hasOne'].includes(field.type)
+    }
+
+    return { inputFor, editable }
+}

package/app/composables/useVectorJobs.ts

@@ -0,0 +1,62 @@
+import type { VectorJob } from '#vector/app/types/vector'
+
+/** Background jobs: list, poll one until it settles, download its file. */
+export function useVectorJobs() {
+    const api = useVectorApi()
+
+    async function list(): Promise<VectorJob[]> {
+        return (await api<{ data: VectorJob[] }>('/vector/jobs')).data
+    }
+
+    async function show(id: number): Promise<VectorJob> {
+        return (await api<{ data: VectorJob }>(`/vector/jobs/${id}`)).data
+    }
+
+    /**
+     * Polls every second (backing off to five) until the job is done or
+     * failed, reporting each state; an aborted signal ends the poll with
+     * the last state seen, so a page that goes away stops asking.
+     */
+    async function watch(id: number, onUpdate?: (job: VectorJob) => void, signal?: AbortSignal): Promise<VectorJob> {
+        let delay = 1000
+
+        for (;;) {
+            const job = await show(id)
+            onUpdate?.(job)
+
+            if (job.status === 'done' || job.status === 'failed' || job.status === 'stalled' || signal?.aborted) {
+                return job
+            }
+
+            await new Promise<void>((resolve) => {
+                const timer = setTimeout(resolve, delay)
+                signal?.addEventListener('abort', () => {
+                    clearTimeout(timer)
+                    resolve()
+                }, { once: true })
+            })
+
+            if (signal?.aborted) {
+                return job
+            }
+
+            delay = Math.min(5000, delay + 500)
+        }
+    }
+
+    async function download(job: VectorJob): Promise<void> {
+        if (!import.meta.client) return
+
+        const response = await asFile(() => api.raw(`/vector/jobs/${job.id}/download`, { responseType: 'blob' }))
+        const url = URL.createObjectURL(response._data as Blob)
+        const link = document.createElement('a')
+        link.href = url
+        link.download = job.fileName ?? `job-${job.id}`
+        document.body.appendChild(link)
+        link.click()
+        link.remove()
+        setTimeout(() => URL.revokeObjectURL(url), 1000)
+    }
+
+    return { list, show, watch, download }
+}

package/app/composables/useVectorLocale.ts

@@ -0,0 +1,70 @@
+import type { VectorLocale, VectorSchemaI18n } from '#vector/app/types/vector'
+import { isRtl, vuetifyLocale } from '#vector/app/i18n'
+
+// The latest language the user picked: an earlier pick still in flight
+// must not apply its answer over it. The UI runs in the browser only, one
+// app per page, so one counter per module is one per session.
+let latestChoice = 0
+
+/**
+ * The admin's language, per user. The descriptor says which language this
+ * user is shown and which ones the administrator lets them choose from;
+ * `choose()` stores the choice as the user's `locale` preference and
+ * reloads the descriptor, whose labels the server translates. Applying a
+ * language switches the UI's strings, Vuetify's, the formatting of dates,
+ * numbers and money, and the page's direction (right to left for Hebrew).
+ */
+export function useVectorLocale() {
+    const nuxtApp = useNuxtApp()
+    const locales = useState<VectorLocale[]>('vector.locales', () => [])
+    const current = computed(() => String(nuxtApp.$vectorI18n.global.locale.value))
+
+    function apply(code: string): void {
+        nuxtApp.$vectorI18n.global.locale.value = code
+        setFormatLocale(code)
+
+        const vuetify = nuxtApp.$vuetify as { locale?: { current: { value: string }, messages: { value: Record<string, unknown> } } } | undefined
+        if (vuetify?.locale) {
+            const tag = vuetifyLocale(code)
+            const known = vuetify.locale.messages.value
+            vuetify.locale.current.value = known[tag] ? tag : (known[code.split('-')[0]!] ? code.split('-')[0]! : 'en')
+        }
+
+        if (import.meta.client) {
+            const known = locales.value.find(l => l.code === code)
+            document.documentElement.lang = code
+            document.documentElement.dir = known ? known.dir : (isRtl(code) ? 'rtl' : 'ltr')
+            try {
+                window.localStorage.setItem('vector.locale', code)
+            } catch {
+                // remembered for the next visit only when storage allows it
+            }
+        }
+    }
+
+    /** Takes what the descriptor says: the language to show and the ones on offer. */
+    function adopt(i18n: VectorSchemaI18n | undefined): void {
+        if (!i18n) return
+        locales.value = i18n.locales
+        if (i18n.locale !== current.value) apply(i18n.locale)
+    }
+
+    /**
+     * The user picks a language: remembered as their preference, then applied
+     * — in that order, since applying it makes every page fetch its labels
+     * again, and the server answers in the preference it has — and the
+     * descriptor reloaded in it.
+     */
+    async function choose(code: string): Promise<void> {
+        const choice = ++latestChoice
+        await useVectorPreferences().put({ locale: code })
+        if (choice !== latestChoice) return
+        apply(code)
+        const schema = await useVectorSchema().load(true)
+        if (choice === latestChoice) adopt(schema.i18n)
+    }
+
+    const direction = computed<'ltr' | 'rtl'>(() => locales.value.find(l => l.code === current.value)?.dir ?? (isRtl(current.value) ? 'rtl' : 'ltr'))
+
+    return { current, locales, direction, apply, adopt, choose }
+}

package/app/composables/useVectorNotifications.ts

@@ -0,0 +1,24 @@
+export interface VectorNotification {
+    text: string
+    color?: 'success' | 'error' | 'warning' | 'info'
+    timeout?: number
+}
+
+/**
+ * The queue VxNotifications renders. Shared app state, so a page, a
+ * store or a fetch hook can notify from anywhere.
+ */
+export function useVectorNotifications() {
+    const queue = useState<VectorNotification[]>('vector.notifications', () => [])
+
+    function notify(text: string, color: VectorNotification['color'] = 'info', timeout?: number) {
+        queue.value.push({ text, color, timeout })
+    }
+
+    return {
+        queue,
+        notify,
+        success: (text: string) => notify(text, 'success'),
+        error: (text: string) => notify(text, 'error', 6000),
+    }
+}

package/app/composables/useVectorNotificationsInbox.ts

@@ -0,0 +1,26 @@
+import type { VectorNotification } from '#vector/app/types/vector'
+
+/** The inbox and its unread count, polled while the admin is open. */
+export function useVectorNotificationsInbox() {
+    const api = useVectorApi()
+    const unread = useState<number>('vector.inbox.unread', () => 0)
+    const items = useState<VectorNotification[]>('vector.inbox.items', () => [])
+
+    async function refresh(): Promise<void> {
+        const inbox = await api<{ data: VectorNotification[], unread: number }>('/vector/notifications')
+        items.value = inbox.data
+        unread.value = inbox.unread
+    }
+
+    async function markRead(id: number): Promise<void> {
+        await api(`/vector/notifications/${id}/read`, { method: 'POST' })
+        await refresh()
+    }
+
+    async function markAllRead(): Promise<void> {
+        await api('/vector/notifications/read-all', { method: 'POST' })
+        await refresh()
+    }
+
+    return { unread, items, refresh, markRead, markAllRead }
+}

package/app/composables/useVectorPreferences.ts

@@ -0,0 +1,30 @@
+/**
+ * Per-user UI preferences, loaded once per session and written through
+ * as they change. Column state lives under `columns.<resource>`.
+ */
+export function useVectorPreferences() {
+    const api = useVectorApi()
+    const preferences = useState<Record<string, unknown> | null>('vector.preferences', () => null)
+
+    async function load(): Promise<Record<string, unknown>> {
+        if (preferences.value === null) {
+            preferences.value = (await api<{ data: Record<string, unknown> }>('/vector/preferences')).data
+        }
+
+        return preferences.value
+    }
+
+    function get<T>(key: string): T | undefined {
+        return preferences.value?.[key] as T | undefined
+    }
+
+    async function put(values: Record<string, unknown>): Promise<void> {
+        preferences.value = (await api<{ data: Record<string, unknown> }>('/vector/preferences', { method: 'PUT', body: values })).data
+    }
+
+    function clear() {
+        preferences.value = null
+    }
+
+    return { preferences, load, get, put, clear }
+}