ads-fe 0.0.1

package/skills/vueuse-functions/references/useManualRefHistory.md

@@ -0,0 +1,204 @@
+---
+category: State
+related: useRefHistory
+---
+
+# useManualRefHistory
+
+Manually track the change history of a ref when the user calls `commit()`, also provides undo and redo functionality
+
+## Usage
+
+```ts {5} twoslash include usage
+import { useManualRefHistory } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const counter = shallowRef(0)
+const { history, commit, undo, redo } = useManualRefHistory(counter)
+
+counter.value += 1
+commit()
+
+console.log(history.value)
+/* [
+  { snapshot: 1, timestamp: 1601912898062 },
+  { snapshot: 0, timestamp: 1601912898061 }
+] */
+```
+
+You can use `undo` to reset the ref value to the last history point.
+
+```ts
+// @include: usage
+// ---cut---
+console.log(counter.value) // 1
+undo()
+console.log(counter.value) // 0
+```
+
+#### History of mutable objects
+
+If you are going to mutate the source, you need to pass a custom clone function or use `clone` `true` as a param, that is a shortcut for a minimal clone function `x => JSON.parse(JSON.stringify(x))` that will be used in both `dump` and `parse`.
+
+```ts {5}
+import { useManualRefHistory } from '@vueuse/core'
+import { ref } from 'vue'
+
+const counter = ref({ foo: 1, bar: 2 })
+const { history, commit, undo, redo } = useManualRefHistory(counter, { clone: true })
+
+counter.value.foo += 1
+commit()
+```
+
+#### Custom Clone Function
+
+To use a full featured or custom clone function, you can set up via the `clone` options.
+
+For example, using [structuredClone](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone):
+
+```ts
+import { useManualRefHistory } from '@vueuse/core'
+
+const refHistory = useManualRefHistory(target, { clone: structuredClone })
+```
+
+Or by using [lodash's `cloneDeep`](https://lodash.com/docs/4.17.15#cloneDeep):
+
+```ts
+import { useManualRefHistory } from '@vueuse/core'
+import { cloneDeep } from 'lodash-es'
+
+const refHistory = useManualRefHistory(target, { clone: cloneDeep })
+```
+
+Or a more lightweight [`klona`](https://github.com/lukeed/klona):
+
+```ts
+import { useManualRefHistory } from '@vueuse/core'
+import { klona } from 'klona'
+
+const refHistory = useManualRefHistory(target, { clone: klona })
+```
+
+#### Custom Dump and Parse Function
+
+Instead of using the `clone` options, you can pass custom functions to control the serialization and parsing. In case you do not need history values to be objects, this can save an extra clone when undoing. It is also useful in case you want to have the snapshots already stringified to be saved to local storage for example.
+
+```ts
+import { useManualRefHistory } from '@vueuse/core'
+
+const refHistory = useManualRefHistory(target, {
+  dump: JSON.stringify,
+  parse: JSON.parse,
+})
+```
+
+### History Capacity
+
+We will keep all the history by default (unlimited) until you explicitly clear them up, you can set the maximal amount of history to be kept by `capacity` options.
+
+```ts
+import { useManualRefHistory } from '@vueuse/core'
+
+const refHistory = useManualRefHistory(target, {
+  capacity: 15, // limit to 15 history records
+})
+
+refHistory.clear() // explicitly clear all the history
+```
+
+## Type Declarations
+
+```ts
+export interface UseRefHistoryRecord<T> {
+  snapshot: T
+  timestamp: number
+}
+export interface UseManualRefHistoryOptions<Raw, Serialized = Raw> {
+  /**
+   * Maximum number of history to be kept. Default to unlimited.
+   */
+  capacity?: number
+  /**
+   * Clone when taking a snapshot, shortcut for dump: JSON.parse(JSON.stringify(value)).
+   * Default to false
+   *
+   * @default false
+   */
+  clone?: boolean | CloneFn<Raw>
+  /**
+   * Serialize data into the history
+   */
+  dump?: (v: Raw) => Serialized
+  /**
+   * Deserialize data from the history
+   */
+  parse?: (v: Serialized) => Raw
+  /**
+   * set data source
+   */
+  setSource?: (source: Ref<Raw>, v: Raw) => void
+}
+export interface UseManualRefHistoryReturn<Raw, Serialized> {
+  /**
+   * Bypassed tracking ref from the argument
+   */
+  source: Ref<Raw>
+  /**
+   * An array of history records for undo, newest comes to first
+   */
+  history: ComputedRef<UseRefHistoryRecord<Serialized>[]>
+  /**
+   * Last history point, source can be different if paused
+   */
+  last: Ref<UseRefHistoryRecord<Serialized>>
+  /**
+   * Same as {@link UseManualRefHistoryReturn.history | history}
+   */
+  undoStack: Ref<UseRefHistoryRecord<Serialized>[]>
+  /**
+   * Records array for redo
+   */
+  redoStack: Ref<UseRefHistoryRecord<Serialized>[]>
+  /**
+   * A ref representing if undo is possible (non empty undoStack)
+   */
+  canUndo: ComputedRef<boolean>
+  /**
+   * A ref representing if redo is possible (non empty redoStack)
+   */
+  canRedo: ComputedRef<boolean>
+  /**
+   * Undo changes
+   */
+  undo: () => void
+  /**
+   * Redo changes
+   */
+  redo: () => void
+  /**
+   * Clear all the history
+   */
+  clear: () => void
+  /**
+   * Create a new history record
+   */
+  commit: () => void
+  /**
+   * Reset ref's value with latest history
+   */
+  reset: () => void
+}
+/**
+ * Track the change history of a ref, also provides undo and redo functionality.
+ *
+ * @see https://vueuse.org/useManualRefHistory
+ * @param source
+ * @param options
+ */
+export declare function useManualRefHistory<Raw, Serialized = Raw>(
+  source: Ref<Raw>,
+  options?: UseManualRefHistoryOptions<Raw, Serialized>,
+): UseManualRefHistoryReturn<Raw, Serialized>
+```

package/skills/vueuse-functions/references/useMath.md

@@ -0,0 +1,47 @@
+---
+category: '@Math'
+---
+
+# useMath
+
+Reactive `Math` methods.
+
+## Usage
+
+```ts
+import { useMath } from '@vueuse/math'
+
+const base = ref(2)
+const exponent = ref(3)
+const result = useMath('pow', base, exponent) // Ref<8>
+
+const num = ref(2)
+const root = useMath('sqrt', num) // Ref<1.4142135623730951>
+
+num.value = 4
+console.log(root.value) // 2
+```
+
+## Type Declarations
+
+```ts
+export type UseMathKeys = keyof {
+  [K in keyof Math as Math[K] extends (...args: any) => any
+    ? K
+    : never]: unknown
+}
+export type UseMathReturn<K extends keyof Math> = ReturnType<
+  Reactified<Math[K], true>
+>
+/**
+ * Reactive `Math` methods.
+ *
+ * @see https://vueuse.org/useMath
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useMath<K extends keyof Math>(
+  key: K,
+  ...args: ArgumentsType<Reactified<Math[K], true>>
+): UseMathReturn<K>
+```

package/skills/vueuse-functions/references/useMax.md

@@ -0,0 +1,36 @@
+---
+category: '@Math'
+---
+
+# useMax
+
+Reactive `Math.max`.
+
+## Usage
+
+```ts
+import { useMax } from '@vueuse/math'
+
+const array = ref([1, 2, 3, 4])
+const max = useMax(array) // Ref<4>
+```
+
+```ts
+import { useMax } from '@vueuse/math'
+
+const a = ref(1)
+const b = ref(3)
+
+const max = useMax(a, b, 2) // Ref<3>
+```
+
+## Type Declarations
+
+```ts
+export declare function useMax(
+  array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>,
+): ComputedRef<number>
+export declare function useMax(
+  ...args: MaybeRefOrGetter<number>[]
+): ComputedRef<number>
+```

package/skills/vueuse-functions/references/useMediaControls.md

@@ -0,0 +1,201 @@
+---
+category: Browser
+---
+
+# useMediaControls
+
+Reactive media controls for both `audio` and `video` elements
+
+## Usage
+
+### Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useMediaControls } from '@vueuse/core'
+import { onMounted, useTemplateRef } from 'vue'
+
+const video = useTemplateRef('video')
+const { playing, currentTime, duration, volume } = useMediaControls(video, {
+  src: 'video.mp4',
+})
+
+// Change initial media properties
+onMounted(() => {
+  volume.value = 0.5
+  currentTime.value = 60
+})
+</script>
+
+<template>
+  <video ref="video" />
+  <button @click="playing = !playing">
+    Play / Pause
+  </button>
+  <span>{{ currentTime }} / {{ duration }}</span>
+</template>
+```
+
+### Providing Captions, Subtitles, etc...
+
+You can provide captions, subtitles, etc in the `tracks` options of the
+`useMediaControls` function. The function will return an array of tracks
+along with two functions for controlling them, `enableTrack`, `disableTrack`, and `selectedTrack`.
+Using these you can manage the currently selected track. `selectedTrack` will
+be `-1` if there is no selected track.
+
+```vue
+<script setup lang="ts">
+import { useMediaControls } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const video = useTemplateRef('video')
+const {
+  tracks,
+  enableTrack
+} = useMediaControls(video, {
+  src: 'video.mp4',
+  tracks: [
+    {
+      default: true,
+      src: './subtitles.vtt',
+      kind: 'subtitles',
+      label: 'English',
+      srcLang: 'en',
+    },
+  ]
+})
+</script>
+
+<template>
+  <video ref="video" />
+  <button v-for="track in tracks" :key="track.id" @click="enableTrack(track)">
+    {{ track.label }}
+  </button>
+</template>
+```
+
+## Type Declarations
+
+```ts
+/**
+ * Many of the jsdoc definitions here are modified version of the
+ * documentation from MDN(https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement)
+ */
+export interface UseMediaSource {
+  /**
+   * The source url for the media
+   */
+  src: string
+  /**
+   * The media codec type
+   */
+  type?: string
+  /**
+   * Specifies the media query for the resource's intended media.
+   */
+  media?: string
+}
+export interface UseMediaTextTrackSource {
+  /**
+   * Indicates that the track should be enabled unless the user's preferences indicate
+   * that another track is more appropriate
+   */
+  default?: boolean
+  /**
+   * How the text track is meant to be used. If omitted the default kind is subtitles.
+   */
+  kind: TextTrackKind
+  /**
+   * A user-readable title of the text track which is used by the browser
+   * when listing available text tracks.
+   */
+  label: string
+  /**
+   * Address of the track (.vtt file). Must be a valid URL. This attribute
+   * must be specified and its URL value must have the same origin as the document
+   */
+  src: string
+  /**
+   * Language of the track text data. It must be a valid BCP 47 language tag.
+   * If the kind attribute is set to subtitles, then srclang must be defined.
+   */
+  srcLang: string
+}
+interface UseMediaControlsOptions extends ConfigurableDocument {
+  /**
+   * The source for the media, may either be a string, a `UseMediaSource` object, or a list
+   * of `UseMediaSource` objects.
+   */
+  src?: MaybeRefOrGetter<string | UseMediaSource | UseMediaSource[]>
+  /**
+   * A list of text tracks for the media
+   */
+  tracks?: MaybeRefOrGetter<UseMediaTextTrackSource[]>
+}
+export interface UseMediaTextTrack {
+  /**
+   * The index of the text track
+   */
+  id: number
+  /**
+   * The text track label
+   */
+  label: string
+  /**
+   * Language of the track text data. It must be a valid BCP 47 language tag.
+   * If the kind attribute is set to subtitles, then srclang must be defined.
+   */
+  language: string
+  /**
+   * Specifies the display mode of the text track, either `disabled`,
+   * `hidden`, or `showing`
+   */
+  mode: TextTrackMode
+  /**
+   * How the text track is meant to be used. If omitted the default kind is subtitles.
+   */
+  kind: TextTrackKind
+  /**
+   * Indicates the track's in-band metadata track dispatch type.
+   */
+  inBandMetadataTrackDispatchType: string
+  /**
+   * A list of text track cues
+   */
+  cues: TextTrackCueList | null
+  /**
+   * A list of active text track cues
+   */
+  activeCues: TextTrackCueList | null
+}
+export interface UseMediaControlsReturn {
+  currentTime: ShallowRef<number>
+  duration: ShallowRef<number>
+  waiting: ShallowRef<boolean>
+  seeking: ShallowRef<boolean>
+  ended: ShallowRef<boolean>
+  stalled: ShallowRef<boolean>
+  buffered: ShallowRef<[number, number][]>
+  playing: ShallowRef<boolean>
+  rate: ShallowRef<number>
+  volume: ShallowRef<number>
+  muted: ShallowRef<boolean>
+  tracks: ShallowRef<UseMediaTextTrack[]>
+  selectedTrack: ShallowRef<number>
+  enableTrack: (
+    track: number | UseMediaTextTrack,
+    disableTracks?: boolean,
+  ) => void
+  disableTrack: (track?: number | UseMediaTextTrack) => void
+  supportsPictureInPicture: boolean
+  togglePictureInPicture: () => Promise<PictureInPictureWindow | void>
+  isPictureInPicture: ShallowRef<boolean>
+  onSourceError: EventHookOn<Event>
+  onPlaybackError: EventHookOn<Event>
+}
+export declare function useMediaControls(
+  target: MaybeRef<HTMLMediaElement | null | undefined>,
+  options?: UseMediaControlsOptions,
+): UseMediaControlsReturn
+```

package/skills/vueuse-functions/references/useMediaQuery.md

@@ -0,0 +1,53 @@
+---
+category: Browser
+---
+
+# useMediaQuery
+
+Reactive [Media Query](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Testing_media_queries). Once you've created a MediaQueryList object, you can check the result of the query or receive notifications when the result changes.
+
+## Usage
+
+```ts
+import { useMediaQuery } from '@vueuse/core'
+
+const isLargeScreen = useMediaQuery('(min-width: 1024px)')
+const isPreferredDark = useMediaQuery('(prefers-color-scheme: dark)')
+```
+
+#### Server Side Rendering and Nuxt
+
+If you are using `useMediaQuery` with SSR enabled, then you need to specify which screen size you would like to render on the server and before hydration to avoid an hydration mismatch
+
+```ts
+import { useMediaQuery } from '@vueuse/core'
+
+const isLarge = useMediaQuery('(min-width: 1024px)', {
+  ssrWidth: 768 // Will enable SSR mode and render like if the screen was 768px wide
+})
+
+console.log(isLarge.value) // always false because ssrWidth of 768px is smaller than 1024px
+onMounted(() => {
+  console.log(isLarge.value) // false if screen is smaller than 1024px, true if larger than 1024px
+})
+```
+
+Alternatively you can set this up globally for your app using [`provideSSRWidth`](../useSSRWidth/index.md)
+
+## Type Declarations
+
+```ts
+/**
+ * Reactive Media Query.
+ *
+ * @see https://vueuse.org/useMediaQuery
+ * @param query
+ * @param options
+ */
+export declare function useMediaQuery(
+  query: MaybeRefOrGetter<string>,
+  options?: ConfigurableWindow & {
+    ssrWidth?: number
+  },
+): ComputedRef<boolean>
+```

package/skills/vueuse-functions/references/useMemoize.md

@@ -0,0 +1,175 @@
+---
+category: Utilities
+---
+
+# useMemoize
+
+Cache results of functions depending on arguments and keep it reactive. It can also be used for asynchronous functions and will reuse existing promises to avoid fetching the same data at the same time.
+
+::: tip
+The results are not cleared automatically. Call `clear()` in case you no longer need the results or use own caching mechanism to avoid memory leaks.
+:::
+
+## Usage
+
+```ts
+import { useMemoize } from '@vueuse/core'
+
+const getUser = useMemoize(
+  async (userId: number): Promise<UserData> =>
+    axios.get(`users/${userId}`).then(({ data }) => data),
+)
+
+const user1 = await getUser(1) // Request users/1
+const user2 = await getUser(2) // Request users/2
+// ...
+const user1 = await getUser(1) // Retrieve from cache
+
+// ...
+const user1 = await getUser.load(1) // Request users/1
+
+// ...
+getUser.delete(1) // Delete cache from user 1
+getUser.clear() // Clear full cache
+```
+
+Combine with `computed` or `computedAsync` to achieve reactivity:
+
+```ts
+import { computedAsync, useMemoize } from '@vueuse/core'
+
+const getUser = useMemoize(
+  async (userId: number): Promise<UserData> =>
+    axios.get(`users/${userId}`).then(({ data }) => data),
+)
+// ---cut---
+const user1 = computedAsync(() => getUser(1))
+// ...
+await getUser.load(1) // Will also update user1
+```
+
+### Resolving cache key
+
+The key for caching is determined by the arguments given to the function and will be serialized by default with `JSON.stringify`.
+This will allow equal objects to receive the same cache key. In case you want to customize the key you can pass `getKey`
+
+::: warning Performance Consideration
+Using `JSON.stringify` as the default key generator can be **slow for large or complex objects**. For better performance with complex arguments, it's highly recommended to provide a custom `getKey` function that generates keys based on primitive values or unique identifiers.
+:::
+
+#### Basic Example
+
+```ts
+import { useMemoize } from '@vueuse/core'
+// ---cut---
+const getUser = useMemoize(
+  async (userId: number, headers: AxiosRequestHeaders): Promise<UserData> =>
+    axios.get(`users/${userId}`, { headers }).then(({ data }) => data),
+  {
+    // Use only userId to get/set cache and ignore headers
+    getKey: (userId, headers) => userId,
+  },
+)
+```
+
+### Customize cache mechanism
+
+By default, the results are cached within a `Map`. You can implement your own mechanism by passing `cache` as options with following structure:
+
+```ts
+export interface MemoizeCache<Key, Value> {
+  /**
+   * Get value for key
+   */
+  get: (key: Key) => Value | undefined
+  /**
+   * Set value for key
+   */
+  set: (key: Key, value: Value) => void
+  /**
+   * Return flag if key exists
+   */
+  has: (key: Key) => boolean
+  /**
+   * Delete value for key
+   */
+  delete: (key: Key) => void
+  /**
+   * Clear cache
+   */
+  clear: () => void
+}
+```
+
+## Type Declarations
+
+```ts
+type CacheKey = any
+/**
+ * Custom memoize cache handler
+ */
+export interface UseMemoizeCache<Key, Value> {
+  /**
+   * Get value for key
+   */
+  get: (key: Key) => Value | undefined
+  /**
+   * Set value for key
+   */
+  set: (key: Key, value: Value) => void
+  /**
+   * Return flag if key exists
+   */
+  has: (key: Key) => boolean
+  /**
+   * Delete value for key
+   */
+  delete: (key: Key) => void
+  /**
+   * Clear cache
+   */
+  clear: () => void
+}
+/**
+ * Memoized function
+ */
+export interface UseMemoizeReturn<Result, Args extends unknown[]> {
+  /**
+   * Get result from cache or call memoized function
+   */
+  (...args: Args): Result
+  /**
+   * Call memoized function and update cache
+   */
+  load: (...args: Args) => Result
+  /**
+   * Delete cache of given arguments
+   */
+  delete: (...args: Args) => void
+  /**
+   * Clear cache
+   */
+  clear: () => void
+  /**
+   * Generate cache key for given arguments
+   */
+  generateKey: (...args: Args) => CacheKey
+  /**
+   * Cache container
+   */
+  cache: UseMemoizeCache<CacheKey, Result>
+}
+export interface UseMemoizeOptions<Result, Args extends unknown[]> {
+  getKey?: (...args: Args) => string | number
+  cache?: UseMemoizeCache<CacheKey, Result>
+}
+/**
+ * Reactive function result cache based on arguments
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useMemoize<Result, Args extends unknown[]>(
+  resolver: (...args: Args) => Result,
+  options?: UseMemoizeOptions<Result, Args>,
+): UseMemoizeReturn<Result, Args>
+```