@prefecthq/prefect-ui-library 2.9.18 → 2.10.0

package/src/compositions/useOptionalRules.ts

@@ -0,0 +1,9 @@
+import { computed, Ref } from 'vue'
+
+// copied and slightly modified from vee-validate since its not exported...
+type GenericValidateFunction = (value: unknown) => boolean | string | Promise<boolean | string>
+type Rules = GenericValidateFunction | GenericValidateFunction[] | undefined
+
+export function useOptionalRules(rules: Rules, apply: Ref<boolean>): Ref<Rules> {
+  return computed(() => apply.value ? rules : undefined)
+}

package/src/compositions/usePaginatedSubscription.ts

@@ -0,0 +1,102 @@
+import { useSubscription, ActionArguments, ActionResponse, SubscribeArguments, UseSubscription, unrefArgs, watchableArgs } from '@prefecthq/vue-compositions'
+import { computed, getCurrentInstance, onUnmounted, reactive, ref, watch } from 'vue'
+import { uniqueValueWatcher } from '@/utilities/reactivity'
+
+export type Paginated = { limit?: number, offset?: number }
+// any is correct here
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PaginatedAction = (filters: Paginated) => Promise<any[]>
+export type UsePaginatedSubscription<T extends PaginatedAction> = {
+  loadMore: () => void,
+} & Omit<UseSubscription<T>, 'promise'>
+
+/**
+ * @deprecated Use dedicated compositions such as useFlowRunInfiniteScroll instead
+ */
+export function usePaginatedSubscription<T extends PaginatedAction>(...[action, args, options = {}]: SubscribeArguments<T>): UsePaginatedSubscription<T> {
+  const subscriptions = reactive<UseSubscription<T>[]>([])
+  const argsWithDefault = args ?? [] as unknown as ActionArguments<T>
+  const pages = ref(0)
+  const watchable = watchableArgs(argsWithDefault)
+
+  let unwatch: ReturnType<typeof watch> | undefined
+
+  const loading = computed(() => subscriptions.some(subscription => subscription.loading))
+  const errored = computed(() => subscriptions.some(subscription => subscription.errored))
+  const error = computed(() => subscriptions.length ? subscriptions[0].error : undefined)
+  const executed = computed(() => subscriptions.some(subscription => subscription.executed))
+  const response = computed(() => subscriptions.flatMap(subscription => subscription.response ?? []) as ActionResponse<T>)
+  const paused = computed(() => subscriptions.some(subscription => subscription.paused))
+  const late = computed(() => subscriptions.some(subscription => subscription.late))
+
+  const unsubscribe = (): void => {
+    subscriptions.forEach(subscription => subscription.unsubscribe())
+  }
+
+  const refresh = async (): Promise<void> => {
+    const promises = subscriptions.map(subscription => subscription.refresh())
+
+    await Promise.all(promises)
+  }
+
+  const isSubscribed = (): boolean => {
+    return subscriptions.every(subscription => subscription.isSubscribed())
+  }
+
+  const loadMore = (): void => {
+    const [unwrappedFilters] = unrefArgs(argsWithDefault)
+    const limit = unwrappedFilters.limit ?? 200
+
+    if (subscriptions.length * limit > response.value.length) {
+      return
+    }
+
+    const offset = (unwrappedFilters.offset ?? limit) * pages.value
+    const subscriptionFilters = [{ ...unwrappedFilters, offset, limit }] as Parameters<T>
+    const subscription = useSubscription<T>(action, subscriptionFilters, options)
+
+    subscriptions.push(reactive(subscription))
+
+    pages.value++
+  }
+
+  if (watchable !== null) {
+    unwatch = uniqueValueWatcher(watchable, () => {
+      if (!isSubscribed()) {
+        unwatch!()
+        return
+      }
+
+      pages.value = 0
+      unsubscribe()
+      subscriptions.splice(0)
+
+      loadMore()
+    }, { deep: true })
+  }
+
+  if (getCurrentInstance()) {
+    onUnmounted(() => {
+      unsubscribe()
+
+      if (unwatch) {
+        unwatch()
+      }
+    })
+  }
+
+  return reactive({
+    loading,
+    executed,
+    errored,
+    error,
+    response,
+    paused,
+    late,
+    unsubscribe,
+    refresh,
+    isSubscribed,
+    loadMore,
+  })
+
+}

package/src/compositions/usePagination.spec.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest'
+import { usePagination } from '@/compositions/usePagination'
+
+describe('usePagination', () => {
+  it('exists', () => {
+    expect(usePagination).toBeDefined()
+  })
+})

package/src/compositions/usePagination.ts

@@ -0,0 +1,213 @@
+import { Getter } from '@prefecthq/prefect-design'
+import { SubscriptionOptions, UseSubscription, useSubscriptionWithDependencies } from '@prefecthq/vue-compositions'
+import merge from 'lodash.merge'
+import { ComputedRef, MaybeRef, Ref, computed, onScopeDispose, reactive, ref, toRef, watch } from 'vue'
+import { GLOBAL_API_LIMIT } from '@/compositions/useFilterPagination'
+import { UseSubscriptions, useSubscriptions } from '@/compositions/useSubscriptions'
+import { repeat } from '@/utilities/arrays'
+
+type PaginationFilter = {
+  limit?: number,
+  offset?: number,
+}
+
+// typescript only lets you use any here
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PaginationParameters = [filter?: PaginationFilter, ...any[]]
+type PaginationFetchAction = (...parameters: PaginationParameters) => Promise<unknown[]>
+type PaginationCountAction = (...parameters: PaginationParameters) => Promise<number>
+
+export type PaginationOptions = SubscriptionOptions & {
+  mode?: 'page' | 'infinite',
+  page?: MaybeRef<number>,
+}
+
+export type UsePaginationParameters<
+  TFetch extends PaginationFetchAction,
+  TFetchParameters extends Getter<Parameters<TFetch> | null>,
+  TCount extends PaginationCountAction,
+  TCountParameters extends Getter<Parameters<TCount> | null>
+> = {
+  fetchMethod: TFetch,
+  fetchParameters: TFetchParameters,
+  countMethod: TCount,
+  countParameters: TCountParameters,
+  options?: PaginationOptions,
+}
+
+export type UsePaginationEntity<
+  TFetch extends PaginationFetchAction,
+  TCount extends PaginationCountAction,
+  TProperty extends string
+> = Omit<UsePagination<TFetch, TCount>, 'results'> & {
+  [ P in TProperty ]: ComputedRef<Awaited<ReturnType<TFetch>>>
+}
+
+export type UsePagination<
+  TFetch extends PaginationFetchAction,
+  TCount extends PaginationCountAction
+> = {
+  subscriptions: UseSubscriptions<TCount | TFetch | (() => undefined)>['subscriptions'],
+  results: ComputedRef<Awaited<ReturnType<TFetch>>>,
+  total: ComputedRef<number>,
+  pages: ComputedRef<number>,
+  page: Ref<number>,
+  next: () => void,
+  previous: () => void,
+}
+
+export function usePagination<
+  TFetch extends PaginationFetchAction,
+  TFetchParameters extends Getter<Parameters<TFetch> | null>,
+  TCount extends PaginationCountAction,
+  TCountParameters extends Getter<Parameters<TCount> | null>
+>({
+  fetchMethod,
+  fetchParameters: fetchParametersGetter,
+  countMethod,
+  countParameters: countParametersGetter,
+  options,
+}: UsePaginationParameters<TFetch, TFetchParameters, TCount, TCountParameters>): UsePagination<TFetch, TCount> {
+
+  type TFetchFilter = Parameters<TFetch>[0]
+
+  const mode = getMode()
+  const page = getPageRef()
+  const pages = computed(() => Math.ceil(total.value / getLimit()))
+
+  const countSubscriptionParameters = computed(() => {
+    if (page.value) {
+      const parameters = countParametersGetter()
+
+      if (parameters) {
+        return merge([], parameters)
+      }
+
+      return parameters
+    }
+
+    return null
+  })
+
+  const countSubscription = useSubscriptionWithDependencies(countMethod, countSubscriptionParameters, options)
+  const total = computed(() => countSubscription.response ?? 0)
+
+  const fetchSubscriptions: UseSubscription<TFetch>[] = reactive([])
+  const results = computed(() => fetchSubscriptions.flatMap(subscription => subscription.response ?? []) as unknown as Awaited<ReturnType<TFetch>>)
+
+  watch([total, page, fetchParametersGetter], ([total, page, parameters]) => {
+    if (total === 0 || page === 0 || parameters === null) {
+      fetchSubscriptions.forEach(subscription => subscription.unsubscribe())
+      fetchSubscriptions.splice(0)
+      return
+    }
+
+    const newSubscriptions = getPagesToFetch(page).map(page => {
+      const parameters = getFetchParametersForPage(page)
+
+      return useSubscriptionWithDependencies(fetchMethod, parameters, options)
+    })
+
+    fetchSubscriptions.forEach(subscription => subscription.unsubscribe())
+    fetchSubscriptions.splice(0, Infinity, ...newSubscriptions)
+  }, { immediate: true, deep: true })
+
+  const { subscriptions } = useSubscriptions(() => [
+    countSubscription,
+    ...fetchSubscriptions,
+  ])
+
+  function next(): void {
+    if (mode === 'page') {
+      page.value++
+      return
+    }
+
+    const shouldLoadNextPage = page.value * getLimit() <= results.value.length
+
+    if (shouldLoadNextPage) {
+      page.value++
+    }
+  }
+
+  function previous(): void {
+    page.value--
+  }
+
+  function getPagesToFetch(page: number): number[] {
+    if (mode === 'page') {
+      return [page]
+    }
+
+    return repeat(page, index => index + 1)
+  }
+
+  function getFetchParametersForPage(page: number): Ref<Parameters<TFetch> | null> {
+    return toRef(() => {
+      const parameters = fetchParametersGetter()
+
+      if (parameters === null) {
+        return null
+      }
+
+      const [filter, ...rest] = parameters
+      const pageFilter = getFetchFilterForPage(page, filter)
+
+      return [pageFilter, ...rest]
+    }) as Ref<Parameters<TFetch> | null>
+  }
+
+  function getFetchFilterForPage(page: number, filter?: TFetchFilter): TFetchFilter {
+    const limit = getLimit()
+    const offset = getPageOffset(page)
+
+    return {
+      ...filter,
+      offset,
+      limit,
+    }
+  }
+
+  function getLimit(): number {
+    const [filter] = fetchParametersGetter() ?? []
+    const limit = filter?.limit ?? GLOBAL_API_LIMIT
+
+    return limit
+  }
+
+  function getPageOffset(page: number): number {
+    const limit = getLimit()
+
+    return (page - 1) * limit
+  }
+
+  function getPageRef(): Ref<number> {
+    if (options?.page) {
+      return ref(options.page)
+    }
+
+    return ref(mode === 'page' ? 1 : 0)
+  }
+
+  function getMode(): Exclude<PaginationOptions['mode'], undefined> {
+    return options?.mode ?? 'page'
+  }
+
+  watch(fetchParametersGetter, () => {
+    page.value = 1
+  }, { deep: true })
+
+  onScopeDispose(() => {
+    subscriptions.unsubscribe()
+  })
+
+  return {
+    subscriptions,
+    results,
+    total,
+    page,
+    pages,
+    next,
+    previous,
+  }
+}

package/src/compositions/useReactiveField.ts

@@ -0,0 +1,21 @@
+import { useField } from 'vee-validate'
+import { Ref, watch } from 'vue'
+
+export function useReactiveField<T>(sourceRef: Ref<T>, ...[name, rules, opts = {}]: Parameters<typeof useField<T>>): ReturnType<typeof useField> {
+  const field = useField<T>(name, rules, {
+    ...opts,
+    initialValue: sourceRef,
+  })
+
+  const { value: fieldRef } = field
+
+  watch(fieldRef, fieldValue => sourceRef.value = fieldValue)
+
+  watch(sourceRef, sourceValue => {
+    if (sourceValue !== fieldRef.value) {
+      fieldRef.value = sourceValue
+    }
+  })
+
+  return field
+}

package/src/compositions/useReactiveForm.ts

@@ -0,0 +1,23 @@
+import { Ref, watch } from 'vue'
+import { useForm } from '@/compositions/useForm'
+
+// using any here to mirror vee-validate's useForm
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useReactiveForm<T extends Record<string, any>>(sourceRef: Ref<T>, ...[opts = {}]: Parameters<typeof useForm<T>>): ReturnType<typeof useForm<T>> {
+  const form = useForm<T>({
+    ...opts,
+  })
+
+  watch(() => form.values, fieldValue => {
+    sourceRef.value = { ...fieldValue }
+  }, { deep: true })
+
+  watch(sourceRef, sourceValue => {
+    // This is a pretty brute-force comparison and will strip out any non-JSON encodable data when doing the comparison
+    if (JSON.stringify(sourceValue) !== JSON.stringify(form.values)) {
+      form.setValues(sourceValue)
+    }
+  })
+
+  return form
+}

package/src/compositions/useSavedFlowRunsSearches.ts

@@ -0,0 +1,66 @@
+import { useSubscription } from '@prefecthq/vue-compositions'
+import { computed, ComputedRef } from 'vue'
+import { useDefaultSavedSearchFilter } from '@/compositions/useDefaultSavedSearchFilter'
+import { useWorkspaceApi } from '@/compositions/useWorkspaceApi'
+import { SavedSearch, SavedSearchCreate } from '@/models'
+import { systemSavedSearches, isSameFilter, systemDefaultSavedSearch, unsavedPartialSearch } from '@/utilities/savedFilters'
+
+export type SavedFlowRunsSearch = SavedSearch & { isDefault: boolean }
+
+type UseSavedFlowRunsSearches = {
+  savedFlowRunsSearches: ComputedRef<SavedFlowRunsSearch[]>,
+  createSavedFlowRunsSearch: (search: SavedSearchCreate) => Promise<SavedSearch>,
+  deleteSavedFlowRunsSearch: (savedSearchId: string) => Promise<void>,
+}
+
+export function useSavedFlowRunsSearches(): UseSavedFlowRunsSearches {
+  const api = useWorkspaceApi()
+  const savedSearchesSubscription = useSubscription(api.savedSearches.getSavedSearches)
+  const savedSearches = computed(() => systemSavedSearches.concat(savedSearchesSubscription.response ?? []))
+
+  const { value: myDefaultSavedFilter } = useDefaultSavedSearchFilter()
+
+  const savedFlowRunsSearches = computed<SavedFlowRunsSearch[]>(() => {
+    let foundSavedSearchForDefaultSavedFilter = false
+
+    const all = savedSearches.value.map(savedSearch => {
+      if (isSameFilter(savedSearch.filters, myDefaultSavedFilter.value)) {
+        foundSavedSearchForDefaultSavedFilter = true
+        return { ...savedSearch, isDefault: true }
+      }
+
+      return { ...savedSearch, isDefault: false }
+    })
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- false positive
+    if (!foundSavedSearchForDefaultSavedFilter) {
+      const unsavedDefault: SavedFlowRunsSearch = {
+        ...unsavedPartialSearch,
+        filters: myDefaultSavedFilter.value,
+        isDefault: true,
+      }
+
+      // insert before the system default so that the readonly custom option is always at the top
+      const systemDefaultIndex = all.findIndex(savedSearch => savedSearch.name === systemDefaultSavedSearch.name)
+
+      all.splice(systemDefaultIndex, 0, unsavedDefault)
+    }
+    return all
+  })
+
+  async function deleteSavedFlowRunsSearch(savedSearchId: string): Promise<void> {
+    await api.savedSearches.deleteSavedSearch(savedSearchId)
+    savedSearchesSubscription.refresh()
+  }
+
+  async function createSavedFlowRunsSearch(search: SavedSearchCreate): Promise<SavedSearch> {
+    const savedSearch = await api.savedSearches.createSavedSearch(search)
+    savedSearchesSubscription.refresh()
+    return savedSearch
+  }
+  return {
+    savedFlowRunsSearches,
+    createSavedFlowRunsSearch,
+    deleteSavedFlowRunsSearch,
+  }
+}

package/src/compositions/useScrollLinking.ts

@@ -0,0 +1,63 @@
+import { onMounted, onUnmounted, ref, Ref } from 'vue'
+
+type DisconnectScrollLink = () => void
+type ScrollLinkReturnValue = {
+  disconnect: DisconnectScrollLink,
+  source: Ref<HTMLElement | undefined>,
+  target: Ref<HTMLElement | undefined>,
+}
+
+/**
+ * The useScrollLinking composition takes 2 optional element references (source, target)
+ * and attaches a scroll event listener to the source. When the scroll event of the
+ * source element is fired, the scroll position of the target is updated to match, producing
+ * a scroll linking effect.
+ *
+ * This composition will tear down when the calling component is unmounted but can be disconnected
+ * early using the returned disconnect method.
+ *
+ * @param source Ref<HTMLElement>
+ * @param target Ref<HTMLElement>
+ * @returns ScrollLinkReturnValue
+ */
+export function useScrollLinking(
+  source?: Ref<HTMLElement>,
+  target?: Ref<HTMLElement>,
+): ScrollLinkReturnValue {
+  const sourceRef = ref(source)
+  const targetRef = ref(target)
+
+  const handleScroll = (): void => {
+    if (!sourceRef.value || !targetRef.value) {
+      return
+    }
+
+    targetRef.value.scrollTop = sourceRef.value.scrollTop
+    targetRef.value.scrollLeft = sourceRef.value.scrollLeft
+  }
+
+  const connect = (): void => {
+    if (!sourceRef.value) {
+      return
+    }
+
+    sourceRef.value.addEventListener('scroll', handleScroll)
+  }
+
+  const disconnect = (): void => {
+    if (!sourceRef.value) {
+      return
+    }
+
+    sourceRef.value.removeEventListener('scroll', handleScroll)
+  }
+
+  onMounted(connect)
+  onUnmounted(disconnect)
+
+  return {
+    disconnect,
+    source: sourceRef,
+    target: targetRef,
+  }
+}

package/src/compositions/useShowModal.ts

@@ -0,0 +1,29 @@
+import { computed, ref, Ref } from 'vue'
+
+type UseShowModal = {
+  showModal: Ref<boolean>,
+  isOpen: Ref<boolean>,
+  open: () => void,
+  close: () => void,
+  toggle: () => void,
+}
+
+export function useShowModal(): UseShowModal {
+  const showModal = ref(false)
+
+  const isOpen = computed(() => showModal.value)
+
+  function open(): void {
+    showModal.value = true
+  }
+
+  function close(): void {
+    showModal.value = false
+  }
+
+  function toggle(): void {
+    showModal.value = !showModal.value
+  }
+
+  return { isOpen, showModal, open, close, toggle }
+}

package/src/compositions/useStatePolling.ts

@@ -0,0 +1,33 @@
+import { SubscriptionOptions } from '@prefecthq/vue-compositions'
+import { ComputedRef, computed, ref } from 'vue'
+import { MaybeRef, PrefectStateNames } from '@/types'
+
+type StateResource = {
+  stateName: string | null,
+}
+
+const stateNamesThatShouldPoll: (string | null)[] = ['Pending', 'Running'] satisfies PrefectStateNames[]
+
+export function useStatePolling(stateName: MaybeRef<string | null>, interval?: number): ComputedRef<SubscriptionOptions>
+export function useStatePolling(resource: MaybeRef<StateResource>, interval?: number): ComputedRef<SubscriptionOptions>
+export function useStatePolling(resourceOrStateName: MaybeRef<StateResource | string | null>, interval: number = 5000): ComputedRef<SubscriptionOptions> {
+  const argRef = ref(resourceOrStateName)
+
+  const shouldPoll = computed(() => {
+    const arg = argRef.value
+
+    if (arg === null) {
+      return false
+    }
+
+    if (typeof arg === 'object') {
+      return stateNamesThatShouldPoll.includes(arg.stateName)
+    }
+
+    return stateNamesThatShouldPoll.includes(arg)
+  })
+
+  return computed<SubscriptionOptions>(() => ({
+    interval: shouldPoll.value ? interval : undefined,
+  }))
+}

package/src/compositions/useSubscriptions.ts

@@ -0,0 +1,52 @@
+import { Action, RefreshChannelOptions, UseSubscription } from '@prefecthq/vue-compositions'
+import { MaybeRefOrGetter, computed, reactive, toValue } from 'vue'
+
+type ExtractAction<T extends readonly UseSubscription<Action>[]> =
+  { [K in keyof T]: T[K] extends UseSubscription<infer V> ? V : never }
+
+export type UseSubscriptions<T extends Action> = {
+  subscriptions: Omit<UseSubscription<T>, 'promise' | 'response' | 'error'> & {
+    responses: UseSubscription<T>['response'][],
+    errors: UseSubscription<T>['error'][],
+  },
+}
+
+export function useSubscriptions<T extends UseSubscription<Action>[]>(subscriptions: MaybeRefOrGetter<T>): UseSubscriptions<ExtractAction<T>[number]> {
+  const source = computed(() => toValue(subscriptions))
+  const loading = computed(() => source.value.some(subscription => subscription.loading))
+  const errored = computed(() => source.value.some(subscription => subscription.errored))
+  const errors = computed(() => source.value.map(subscription => subscription.error))
+  const executed = computed(() => source.value.length > 0 && source.value.every(subscription => subscription.executed))
+  const responses = computed(() => source.value.map(subscription => subscription.response))
+  const paused = computed(() => source.value.some(subscription => subscription.paused))
+  const late = computed(() => source.value.some(subscription => subscription.late))
+
+  const unsubscribe = (): void => {
+    source.value.forEach(subscription => subscription.unsubscribe())
+  }
+
+  const refresh = async (options?: RefreshChannelOptions): Promise<void> => {
+    const promises = source.value.map(subscription => subscription.refresh(options))
+
+    await Promise.all(promises)
+  }
+
+  const isSubscribed = (): boolean => {
+    return source.value.every(subscription => subscription.isSubscribed())
+  }
+
+  const response: UseSubscriptions<ExtractAction<T>[number]>['subscriptions'] = reactive({
+    loading,
+    errored,
+    errors,
+    executed,
+    paused,
+    late,
+    responses,
+    unsubscribe,
+    refresh,
+    isSubscribed,
+  })
+
+  return { subscriptions: response }
+}

package/src/compositions/useTabs.ts

@@ -0,0 +1,38 @@
+import { computed, ComputedRef, Ref, ref, watch } from 'vue'
+import { MaybeRef } from '@/types'
+
+export type ConditionalTab = {
+  label: string,
+  hidden?: boolean,
+}
+
+export type UseTabs = {
+  tabs: ComputedRef<string[]>,
+  tab: Ref<string | undefined>,
+}
+
+export function useTabs(tabs: MaybeRef<ConditionalTab[]>, tab?: MaybeRef<string | undefined>): UseTabs {
+  const tabsRef = ref(tabs)
+  const visibleTabs = computed(() => tabsRef.value.filter(tab => tab.hidden !== true).map(tab => tab.label))
+  const firstVisibleTab = computed(() => visibleTabs.value.at(0))
+  const tabRef = ref(tab ?? firstVisibleTab.value)
+
+  watch(visibleTabs, visible => {
+    const tab = tabRef.value
+
+    if (tab === undefined) {
+      return
+    }
+
+    if (visible.includes(tab)) {
+      return
+    }
+
+    tabRef.value = firstVisibleTab.value
+  }, { immediate: true })
+
+  return {
+    tabs: visibleTabs,
+    tab: tabRef,
+  }
+}