@xen-orchestra/web-core 0.26.0 → 0.27.0

package/lib/packages/form-select/use-form-select.ts

@@ -7,34 +7,33 @@ import {
 } from '@core/packages/collection'
 import type { EmptyObject, MaybeArray } from '@core/types/utility.type.ts'
 import { toArray } from '@core/utils/to-array.utils.ts'
-import type {
-  ExtractValue,
-  FormOptionCollectionItemProperties,
-  FormSelect,
-  FormSelectId,
-  GetOptionLabel,
-  GetOptionValue,
-  UseFormSelectReturn,
-} from './types.ts'
-import { computed, type ComputedRef, type MaybeRefOrGetter, provide, ref, type Ref, toValue, watch } from 'vue'
+import { computed, type ComputedRef, type MaybeRefOrGetter, provide, ref, type Ref, toRaw, toValue, watch } from 'vue'
 import { guessLabel } from './guess-label.ts'
 import { guessValue } from './guess-value.ts'
 import { normalizeSearchTerm } from './normalize-search-term.ts'
+import {
+  EMPTY_OPTION,
+  type ExtractValue,
+  type FormOptionCollectionItemProperties,
+  type FormSelect,
+  type FormSelectId,
+  type GetOptionLabel,
+  type GetOptionValue,
+  type UseFormSelectReturn,
+} from './types.ts'
 
 // Overload #1: Source is CollectionItemId
 
 export function useFormSelect<
-  TBaseSource extends CollectionItemId,
-  TAllowEmpty extends boolean = false,
+  TSource extends CollectionItemId,
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config?: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -44,32 +43,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option?: {
-      id?: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #2: Source is an object with id and label
 
 export function useFormSelect<
-  TBaseSource extends { id: CollectionItemId; label: string },
-  TAllowEmpty extends boolean = false,
+  TSource extends { id: CollectionItemId; label: string },
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config?: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -79,32 +82,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option?: {
-      id?: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #3: Source is an object with id only
 
 export function useFormSelect<
-  TBaseSource extends { id: CollectionItemId },
-  TAllowEmpty extends boolean = false,
+  TSource extends { id: CollectionItemId },
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -114,32 +121,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option: {
-      id?: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #4: Source is an object with label only
 
 export function useFormSelect<
-  TBaseSource extends { label: string },
-  TAllowEmpty extends boolean = false,
+  TSource extends { label: string },
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -149,32 +160,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option: {
-      id: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #5: Any other case
 
 export function useFormSelect<
-  TBaseSource,
-  TAllowEmpty extends boolean = false,
+  TSource,
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -184,32 +199,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option: {
-      id: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Implementation
 
 export function useFormSelect<
-  TBaseSource,
-  TAllowEmpty extends boolean = false,
+  TSource,
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  baseSources: MaybeRefOrGetter<TBaseSource[]>,
+  baseSources: MaybeRefOrGetter<TSource[]>,
   config?: {
-    allowEmpty?: MaybeRefOrGetter<boolean>
     multiple?: MaybeRefOrGetter<boolean>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -219,17 +238,23 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option?: {
-      id?: GetItemId<TBaseSource>
-      value?: GetOptionValue<$TSource, TCustomProperties>
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: GetOptionValue<TSource, TCustomProperties>
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple> {
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple> {
   const searchTerm = ref('')
 
   const normalizedSearchTerm = computed(() => normalizeSearchTerm(searchTerm))
@@ -249,8 +274,8 @@ export function useFormSelect<
   const isSearchable = computed(() => toValue(config?.searchable) ?? false)
 
   const sources = computed(() =>
-    config?.allowEmpty ? [undefined, ...toValue(baseSources)] : toValue(baseSources)
-  ) as ComputedRef<$TSource[]>
+    config?.emptyOption !== undefined ? [EMPTY_OPTION, ...toValue(baseSources)] : toValue(baseSources)
+  ) as ComputedRef<(TSource | typeof EMPTY_OPTION)[]>
 
   const {
     items: allOptions,
@@ -258,12 +283,25 @@ export function useFormSelect<
     useFlag,
   } = useCollection(sources, {
     itemId: source =>
-      source === undefined ? '__EMPTY_OPTION__' : guessItemId(source as TBaseSource, config?.option?.id),
+      source === EMPTY_OPTION ? '__EMPTY_OPTION__' : guessItemId(source as TSource, config?.option?.id),
     flags: {
       active: { multiple: false },
       selected: { multiple: isMultiple },
     },
     properties: (source): FormOptionCollectionItemProperties<TCustomProperties, $TValue> => {
+      if (source === EMPTY_OPTION) {
+        const emptyOption = toValue(config?.emptyOption)
+
+        return {
+          value: computed(() => emptyOption?.value as $TValue),
+          label: computed(() => emptyOption?.label ?? ''),
+          selectedLabel: computed(() => emptyOption?.selectedLabel),
+          matching: computed(() => normalizedSearchTerm.value === ''),
+          disabled: computed(() => false),
+          ...(emptyOption?.properties ?? ({} as TCustomProperties)),
+        }
+      }
+
       const customProperties = config?.option?.properties?.(source) ?? ({} as TCustomProperties)
       const label = computed(() => guessLabel(source, customProperties, config?.option?.label))
       const value = computed(() => guessValue(source, customProperties, config?.option?.value) as $TValue)
@@ -296,7 +334,7 @@ export function useFormSelect<
 
   const { items: options } = useSubset(option => option.properties.matching)
 
-  const { items: selectedOptions } = useFlag('selected')
+  const { items: selectedOptions, toggleAll: toggleSelectAll } = useFlag('selected')
 
   const selectedOption = computed(() => selectedOptions.value[0])
 
@@ -318,12 +356,18 @@ export function useFormSelect<
     watch(
       model,
       modelValue => {
+        toggleSelectAll(false)
+
         if (isMultiple.value) {
           allOptions.value.forEach(option => {
-            option.toggleFlag('selected', (modelValue as $TValue[]).includes(option.properties.value as $TValue))
+            if ((modelValue as $TValue[]).includes(toRaw(option.properties.value) as $TValue)) {
+              option.toggleFlag('selected', true)
+            }
           })
         } else {
-          allOptions.value.find(option => option.properties.value === modelValue)?.toggleFlag('selected', true)
+          allOptions.value
+            .find(option => toRaw(option.properties.value) === toRaw(modelValue))
+            ?.toggleFlag('selected', true)
         }
       },
       { immediate: true }
@@ -358,14 +402,14 @@ export function useFormSelect<
     selectedOption,
     selectedOptions,
     selectedLabel,
-  } satisfies FormSelect<TCustomProperties, any> as FormSelect<TCustomProperties, $TSource, $TValue, TMultiple>
+  } satisfies FormSelect<TCustomProperties, any> as FormSelect<TCustomProperties, TSource, $TValue, TMultiple>
 
-  const id = Symbol('useFormSelect ID') as FormSelectId<TCustomProperties, $TSource, $TValue, TMultiple>
+  const id = Symbol('useFormSelect ID') as FormSelectId<TCustomProperties, TSource, $TValue, TMultiple>
 
   provide(id, select)
 
   return {
     id,
     ...select,
-  } satisfies UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+  } satisfies UseFormSelectReturn<TCustomProperties, TSource, $TValue, TMultiple>
 }

package/lib/packages/remote-resource/README.md

@@ -0,0 +1,115 @@
+# `defineRemoteResource` documentation
+
+This utility will create a function that can be used to fetch data from a remote resource (i.e., an API endpoint)
+
+When called, a subscription to the resource is registered.
+
+If multiple Components call that same function, a subscription will be registered for each of them.
+
+They will share the same data and state, which means that the data will be fetched only once and shared across all Components.
+
+The fetch will start automatically when at least one Component is using the resource, then, when the last Component releases the resource, the polling will stop.
+
+The data is cached for a certain duration, so if a Component remounts in the frame time, the data will be retrieved from the cache to be displayed immediately, while the data is being fetched again in the background.
+
+## Basic usage
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+})
+```
+
+By default, the initial data (`TData`) will be `undefined`, the returned state will be `{ data: Ref<TData> }` and when new data is received, it will just replace the previous one.
+
+```typescript
+const { data } = useMyResource()
+```
+
+## Initial data, state and received data handling
+
+The initial data, the state and what happen when data is retrieved can be customized by passing the `initialData`, `state` and `onDataReceived` properties:
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+  initialData: () => {} as Partial<MyResource>,
+  state: (data) => {
+    return {
+      myResource: data,
+      customProp: computed(() => data.foobar)
+    }
+  },
+  onDataReceived: (currentData, receivedData) => {
+    deepMerge(currentData.value, receivedData)
+  }
+}
+
+const { myResource, customProp } = useMyResource()
+```
+
+## Context
+
+The context is available in the `$context` property of the returned state.
+
+It contains the following properties:
+
+| Property      | Type                              | Description                                                                        |
+| ------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
+| `scope`       | `EffectScope`                     | The Vue effect scope used to be shared across the resource and its dependencies    |
+| `args`        | `any[]`                           | The arguments passed to the `useMyResource` function                               |
+| `isReady`     | `ComputedRef<boolean>`            | Indicates if the resource is ready (i.e., the data has been fetched at least once) |
+| `hasError`    | `ComputedRef<boolean>`            | Indicates if an error occurred during the last fetch                               |
+| `lastError`   | `ComputedRef<Error \| undefined>` | The last error that occurred during the fetch, if any                              |
+| `isEnabled`   | `Ref<boolean>`                    | Whether the resource is enabled (execute the request) or not                       |
+| `enable`      | `() => void`                      | Function to manually enable the resource                                           |
+| `disable`     | `() => void`                      | Function to manually disable the resource                                          |
+| `forceReload` | `() => void`                      | Function to manually reload the resource                                           |
+
+```typescript
+const { myResource, $context } = useMyResource()
+```
+
+It's also passed as the second argument of the `state` builder and can be used to extend the resource state.
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+  state: (data, context) => ({
+    myResource: data,
+    isMyResourceReady: context.isReady,
+  }),
+})
+
+const { myResource, isMyResourceReady } = useMyResource()
+```
+
+## Dynamic URLs
+
+You can define a dynamic URL by using a function that returns the URL string.
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: (id: string) => `/api/path/to/resource/${id}`,
+})
+
+const { id } = defineProps<{
+  id: string
+}>()
+
+const { data } = useMyResource(() => id)
+```
+
+## Polling and caching
+
+By default, the resource will poll for updates every 30 seconds and cache the result for 10 seconds.
+
+This can be customized by passing the `pollingIntervalMs` and `cacheDurationMs` properties:
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+  pollingIntervalMs: 60_000, // Poll every 60 seconds
+  cacheDurationMs: 5 * 60_000, // Cache for 5 minutes
+})
+```