devskill 2.0.2

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

@@ -0,0 +1,285 @@
+---
+category: State
+related: useManualRefHistory
+---
+
+# useRefHistory
+
+Track the change history of a ref, also provides undo and redo functionality
+
+<CourseLink href="https://vueschool.io/lessons/ref-history-with-vueuse?friend=vueuse">Learn useRefHistory with this FREE video lesson from Vue School!</CourseLink>
+
+## Usage
+
+```ts {5} twoslash include usage
+import { useRefHistory } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const counter = shallowRef(0)
+const { history, undo, redo } = useRefHistory(counter)
+```
+
+Internally, `watch` is used to trigger a history point when the ref value is modified. This means that history points are triggered asynchronously batching modifications in the same "tick".
+
+```ts
+// @include: usage
+// ---cut---
+counter.value += 1
+
+await nextTick()
+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
+```
+
+### Objects / arrays
+
+When working with objects or arrays, since changing their attributes does not change the reference, it will not trigger the committing. To track attribute changes, you would need to pass `deep: true`. It will create clones for each history record.
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+// ---cut---
+const state = ref({
+  foo: 1,
+  bar: 'bar',
+})
+
+const { history, undo, redo } = useRefHistory(state, {
+  deep: true,
+})
+
+state.value.foo = 2
+
+await nextTick()
+console.log(history.value)
+/* [
+  { snapshot: { foo: 2, bar: 'bar' } },
+  { snapshot: { foo: 1, bar: 'bar' } }
+] */
+```
+
+#### Custom Clone Function
+
+`useRefHistory` only embeds the minimal clone function `x => JSON.parse(JSON.stringify(x))`. 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 { useRefHistory } from '@vueuse/core'
+
+const refHistory = useRefHistory(target, { clone: structuredClone })
+```
+
+Or by using [lodash's `cloneDeep`](https://lodash.com/docs/4.17.15#cloneDeep):
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+import { cloneDeep } from 'lodash-es'
+
+const refHistory = useRefHistory(target, { clone: cloneDeep })
+```
+
+Or a more lightweight [`klona`](https://github.com/lukeed/klona):
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+import { klona } from 'klona'
+
+const refHistory = useRefHistory(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 { useRefHistory } from '@vueuse/core'
+
+const refHistory = useRefHistory(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 { useRefHistory } from '@vueuse/core'
+// ---cut---
+const refHistory = useRefHistory(target, {
+  capacity: 15, // limit to 15 history records
+})
+
+refHistory.clear() // explicitly clear all the history
+```
+
+### History WatchOptionFlush Timing
+
+From [Vue's documentation](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing): Vue's reactivity system buffers invalidated effects and flush them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick".
+
+In the same way as `watch`, you can modify the flush timing using the `flush` option.
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+// ---cut---
+const refHistory = useRefHistory(target, {
+  flush: 'sync', // options 'pre' (default), 'post' and 'sync'
+})
+```
+
+The default is `'pre'`, to align this composable with the default for Vue's watchers. This also helps to avoid common issues, like several history points generated as part of a multi-step update to a ref value that can break invariants of the app state. You can use `commit()` in case you need to create multiple history points in the same "tick"
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+// ---cut---
+const r = shallowRef(0)
+const { history, commit } = useRefHistory(r)
+
+r.value = 1
+commit()
+
+r.value = 2
+commit()
+
+console.log(history.value)
+/* [
+  { snapshot: 2 },
+  { snapshot: 1 },
+  { snapshot: 0 },
+] */
+```
+
+On the other hand, when using flush `'sync'`, you can use `batch(fn)` to generate a single history point for several sync operations
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+// ---cut---
+const r = ref({ names: [], version: 1 })
+const { history, batch } = useRefHistory(r, { flush: 'sync' })
+
+batch(() => {
+  r.value.names.push('Lena')
+  r.value.version++
+})
+
+console.log(history.value)
+/* [
+  { snapshot: { names: [ 'Lena' ], version: 2 },
+  { snapshot: { names: [], version: 1 },
+] */
+```
+
+If `{ flush: 'sync', deep: true }` is used, `batch` is also useful when doing a mutable `splice` in an array. `splice` can generate up to three atomic operations that will be pushed to the ref history.
+
+```ts
+import { useRefHistory } from '@vueuse/core'
+// ---cut---
+const arr = ref([1, 2, 3])
+const { history, batch } = useRefHistory(arr, { deep: true, flush: 'sync' })
+
+batch(() => {
+  arr.value.splice(1, 1) // batch ensures only one history point is generated
+})
+```
+
+Another option is to avoid mutating the original ref value using `arr.value = [...arr.value].splice(1,1)`.
+
+## Recommended Readings
+
+- [History and Persistence](https://patak.dev/vue/history-and-persistence.html) - by [@patak-dev](https://github.com/patak-dev)
+
+## Type Declarations
+
+```ts
+export interface UseRefHistoryOptions<Raw, Serialized = Raw>
+  extends ConfigurableEventFilter, ConfigurableFlush {
+  /**
+   * Watch for deep changes, default to false
+   *
+   * When set to true, it will also create clones for values store in the history
+   *
+   * @default false
+   */
+  deep?: boolean
+  /**
+   * 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
+  /**
+   * Function to determine if the commit should proceed
+   * @param oldValue Previous value
+   * @param newValue New value
+   * @returns boolean indicating if commit should proceed
+   */
+  shouldCommit?: (oldValue: Raw | undefined, newValue: Raw) => boolean
+}
+export interface UseRefHistoryReturn<
+  Raw,
+  Serialized,
+> extends UseManualRefHistoryReturn<Raw, Serialized> {
+  /**
+   * A ref representing if the tracking is enabled
+   */
+  isTracking: Ref<boolean>
+  /**
+   * Pause change tracking
+   */
+  pause: () => void
+  /**
+   * Resume change tracking
+   *
+   * @param [commit] if true, a history record will be create after resuming
+   */
+  resume: (commit?: boolean) => void
+  /**
+   * A sugar for auto pause and auto resuming within a function scope
+   *
+   * @param fn
+   */
+  batch: (fn: (cancel: Fn) => void) => void
+  /**
+   * Clear the data and stop the watch
+   */
+  dispose: () => void
+}
+/**
+ * Track the change history of a ref, also provides undo and redo functionality.
+ *
+ * @see https://vueuse.org/useRefHistory
+ * @param source
+ * @param options
+ */
+export declare function useRefHistory<Raw, Serialized = Raw>(
+  source: Ref<Raw>,
+  options?: UseRefHistoryOptions<Raw, Serialized>,
+): UseRefHistoryReturn<Raw, Serialized>
+```

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

@@ -0,0 +1,109 @@
+---
+category: Elements
+---
+
+# useResizeObserver
+
+Reports changes to the dimensions of an Element's content or the border-box
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useResizeObserver } from '@vueuse/core'
+import { ref, useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const text = ref('')
+
+useResizeObserver(el, (entries) => {
+  const entry = entries[0]
+  const { width, height } = entry.contentRect
+  text.value = `width: ${width}, height: ${height}`
+})
+</script>
+
+<template>
+  <div ref="el">
+    {{ text }}
+  </div>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script setup lang="ts">
+import { vResizeObserver } from '@vueuse/components'
+
+const text = ref('')
+
+function onResizeObserver(entries) {
+  const [entry] = entries
+  const { width, height } = entry.contentRect
+  text.value = `width: ${width}, height: ${height}`
+}
+</script>
+
+<template>
+  <div v-resize-observer="onResizeObserver">
+    {{ text }}
+  </div>
+</template>
+```
+
+[ResizeObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
+
+## Type Declarations
+
+```ts
+/**
+ * @deprecated This interface is now available in the DOM lib.
+ * Use the global {@link globalThis.ResizeObserverSize} instead.
+ */
+export interface ResizeObserverSize {
+  readonly inlineSize: number
+  readonly blockSize: number
+}
+/**
+ * @deprecated This interface is now available in the DOM lib.
+ * Use the global {@link globalThis.ResizeObserverEntry} instead.
+ */
+export interface ResizeObserverEntry {
+  readonly target: Element
+  readonly contentRect: DOMRectReadOnly
+  readonly borderBoxSize: ReadonlyArray<ResizeObserverSize>
+  readonly contentBoxSize: ReadonlyArray<ResizeObserverSize>
+  readonly devicePixelContentBoxSize: ReadonlyArray<ResizeObserverSize>
+}
+/**
+ * @deprecated This interface is now available in the DOM lib.
+ * Use the global {@link globalThis.ResizeObserverCallback} instead.
+ */
+export type ResizeObserverCallback = (
+  entries: ReadonlyArray<ResizeObserverEntry>,
+  observer: ResizeObserver,
+) => void
+export interface UseResizeObserverOptions
+  extends ResizeObserverOptions, ConfigurableWindow {}
+/**
+ * Reports changes to the dimensions of an Element's content or the border-box
+ *
+ * @see https://vueuse.org/useResizeObserver
+ * @param target
+ * @param callback
+ * @param options
+ */
+export declare function useResizeObserver(
+  target:
+    | MaybeComputedElementRef
+    | MaybeComputedElementRef[]
+    | MaybeRefOrGetter<MaybeElement[]>,
+  callback: globalThis.ResizeObserverCallback,
+  options?: UseResizeObserverOptions,
+): {
+  isSupported: ComputedRef<boolean>
+  stop: () => void
+}
+export type UseResizeObserverReturn = ReturnType<typeof useResizeObserver>
+```

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

@@ -0,0 +1,31 @@
+---
+category: '@Math'
+---
+
+# useRound
+
+Reactive `Math.round`.
+
+## Usage
+
+```ts
+import { useRound } from '@vueuse/math'
+
+const value = ref(20.49)
+const result = useRound(value) // 20
+```
+
+## Type Declarations
+
+```ts
+/**
+ * Reactive `Math.round`.
+ *
+ * @see https://vueuse.org/useRound
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useRound(
+  value: MaybeRefOrGetter<number>,
+): ComputedRef<number>
+```

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

@@ -0,0 +1,27 @@
+---
+category: '@Router'
+---
+
+# useRouteHash
+
+Shorthand for a reactive `route.hash`.
+
+## Usage
+
+```ts
+import { useRouteHash } from '@vueuse/router'
+
+const search = useRouteHash()
+
+console.log(search.value) // route.hash
+search.value = 'foobar' // router.replace({ hash: 'foobar' })
+```
+
+## Type Declarations
+
+```ts
+export declare function useRouteHash(
+  defaultValue?: MaybeRefOrGetter<RouteHashValueRaw>,
+  { mode, route, router }?: ReactiveRouteOptions,
+): Ref<RouteHashValueRaw, RouteHashValueRaw>
+```

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

@@ -0,0 +1,38 @@
+---
+category: '@Router'
+---
+
+# useRouteParams
+
+Shorthand for a reactive `route.params`.
+
+## Usage
+
+```ts
+import { useRouteParams } from '@vueuse/router'
+
+const userId = useRouteParams('userId')
+
+const userId = useRouteParams('userId', '-1') // or with a default value
+
+const userId = useRouteParams('page', '1', { transform: Number }) // or transforming value
+
+console.log(userId.value) // route.params.userId
+userId.value = '100' // router.replace({ params: { userId: '100' } })
+```
+
+## Type Declarations
+
+```ts
+export declare function useRouteParams(
+  name: string,
+): Ref<null | string | string[]>
+export declare function useRouteParams<
+  T extends RouteParamValueRaw = RouteParamValueRaw,
+  K = T,
+>(
+  name: string,
+  defaultValue?: MaybeRefOrGetter<T>,
+  options?: ReactiveRouteOptionsWithTransform<T, K>,
+): Ref<K>
+```

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

@@ -0,0 +1,79 @@
+---
+category: '@Router'
+---
+
+# useRouteQuery
+
+Shorthand for a reactive `route.query`. Updates the URL query parameters when the ref changes.
+
+## Usage
+
+```ts
+import { useRouteQuery } from '@vueuse/router'
+
+const search = useRouteQuery('search')
+
+const search = useRouteQuery('search', 'foo') // or with a default value
+
+const page = useRouteQuery('page', '1', { transform: Number }) // or transforming value
+
+console.log(search.value) // route.query.search
+search.value = 'foobar' // router.replace({ query: { search: 'foobar' } })
+```
+
+### Navigation Mode
+
+By default, changes use `router.replace()`. Set `mode: 'push'` to use `router.push()` instead.
+
+```ts
+import { useRouteQuery } from '@vueuse/router'
+
+const search = useRouteQuery('search', '', { mode: 'push' })
+```
+
+### Bidirectional Transform
+
+You can provide separate `get` and `set` transforms for reading and writing values.
+
+```ts
+import { useRouteQuery } from '@vueuse/router'
+
+const filters = useRouteQuery('filters', [], {
+  transform: {
+    get: v => v ? v.split(',') : [],
+    set: v => v.join(','),
+  },
+})
+
+// Reading: 'a,b,c' -> ['a', 'b', 'c']
+// Writing: ['a', 'b', 'c'] -> 'a,b,c'
+```
+
+### Default Value Behavior
+
+When the value equals the default value, the query parameter is removed from the URL.
+
+```ts
+import { useRouteQuery } from '@vueuse/router'
+
+const page = useRouteQuery('page', '1')
+
+page.value = '2' // URL: ?page=2
+page.value = '1' // URL: (no page param, since it equals default)
+```
+
+## Type Declarations
+
+```ts
+export declare function useRouteQuery(
+  name: string,
+): Ref<undefined | null | string | string[]>
+export declare function useRouteQuery<
+  T extends RouteQueryValueRaw = RouteQueryValueRaw,
+  K = T,
+>(
+  name: string,
+  defaultValue?: MaybeRefOrGetter<T>,
+  options?: ReactiveRouteOptionsWithTransform<T, K>,
+): Ref<K>
+```

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

@@ -0,0 +1,47 @@
+---
+category: Browser
+---
+
+# useSSRWidth
+
+Used to set a global viewport width which will be used when rendering SSR components that rely on the viewport width like [`useMediaQuery`](../useMediaQuery/index.md) or [`useBreakpoints`](../useBreakpoints/index.md)
+
+## Usage
+
+```ts
+import { provideSSRWidth } from '@vueuse/core'
+
+const app = createApp(App)
+
+provideSSRWidth(500, app)
+```
+
+Or in the root component
+
+```vue
+<script setup lang="ts">
+import { provideSSRWidth } from '@vueuse/core'
+
+provideSSRWidth(500)
+</script>
+```
+
+To retrieve the provided value if you need it in a subcomponent
+
+```vue
+<script setup lang="ts">
+import { useSSRWidth } from '@vueuse/core'
+
+const width = useSSRWidth()
+</script>
+```
+
+## Type Declarations
+
+```ts
+export declare function useSSRWidth(): number | undefined
+export declare function provideSSRWidth(
+  width: number | null,
+  app?: App<unknown>,
+): void
+```