devskill 2.0.2

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

@@ -0,0 +1,195 @@
+---
+category: Reactivity
+related: syncRefs
+---
+
+# syncRef
+
+Two-way refs synchronization.
+
+## Usage
+
+```ts
+import { syncRef } from '@vueuse/core'
+
+const a = ref('a')
+const b = ref('b')
+
+const stop = syncRef(a, b)
+
+console.log(a.value) // a
+
+b.value = 'foo'
+
+console.log(a.value) // foo
+
+a.value = 'bar'
+
+console.log(b.value) // bar
+```
+
+### One directional
+
+```ts
+import { syncRef } from '@vueuse/core'
+
+const a = ref('a')
+const b = ref('b')
+
+const stop = syncRef(a, b, { direction: 'rtl' })
+```
+
+### Custom Transform
+
+```ts
+import { syncRef } from '@vueuse/core'
+
+const a = ref(10)
+const b = ref(2)
+
+const stop = syncRef(a, b, {
+  transform: {
+    ltr: left => left * 2,
+    rtl: right => right / 2
+  }
+})
+
+console.log(b.value) // 20
+
+b.value = 30
+
+console.log(a.value) // 15
+```
+
+## Type Declarations
+
+```ts
+type Direction = "ltr" | "rtl" | "both"
+type SpecificFieldPartial<T, K extends keyof T> = Partial<Pick<T, K>> &
+  Omit<T, K>
+/**
+ * A = B
+ */
+type Equal<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+/**
+ * A ∩ B ≠ ∅
+ */
+type IntersectButNotEqual<A, B> =
+  Equal<A, B> extends true ? false : A & B extends never ? false : true
+/**
+ * A ⊆ B
+ */
+type IncludeButNotEqual<A, B> =
+  Equal<A, B> extends true ? false : A extends B ? true : false
+/**
+ * A ∩ B = ∅
+ */
+type NotIntersect<A, B> =
+  Equal<A, B> extends true ? false : A & B extends never ? true : false
+interface EqualType<
+  D extends Direction,
+  L,
+  R,
+  O extends keyof Transform<L, R> = D extends "both" ? "ltr" | "rtl" : D,
+> {
+  transform?: SpecificFieldPartial<Pick<Transform<L, R>, O>, O>
+}
+type StrictIncludeMap<
+  IncludeType extends "LR" | "RL",
+  D extends Exclude<Direction, "both">,
+  L,
+  R,
+> = Equal<[IncludeType, D], ["LR", "ltr"]> &
+  Equal<[IncludeType, D], ["RL", "rtl"]> extends true
+  ? {
+      transform?: SpecificFieldPartial<Pick<Transform<L, R>, D>, D>
+    }
+  : {
+      transform: Pick<Transform<L, R>, D>
+    }
+type StrictIncludeType<
+  IncludeType extends "LR" | "RL",
+  D extends Direction,
+  L,
+  R,
+> = D extends "both"
+  ? {
+      transform: SpecificFieldPartial<
+        Transform<L, R>,
+        IncludeType extends "LR" ? "ltr" : "rtl"
+      >
+    }
+  : D extends Exclude<Direction, "both">
+    ? StrictIncludeMap<IncludeType, D, L, R>
+    : never
+type IntersectButNotEqualType<D extends Direction, L, R> = D extends "both"
+  ? {
+      transform: Transform<L, R>
+    }
+  : D extends Exclude<Direction, "both">
+    ? {
+        transform: Pick<Transform<L, R>, D>
+      }
+    : never
+type NotIntersectType<D extends Direction, L, R> = IntersectButNotEqualType<
+  D,
+  L,
+  R
+>
+interface Transform<L, R> {
+  ltr: (left: L) => R
+  rtl: (right: R) => L
+}
+type TransformType<D extends Direction, L, R> =
+  Equal<L, R> extends true
+    ? EqualType<D, L, R>
+    : IncludeButNotEqual<L, R> extends true
+      ? StrictIncludeType<"LR", D, L, R>
+      : IncludeButNotEqual<R, L> extends true
+        ? StrictIncludeType<"RL", D, L, R>
+        : IntersectButNotEqual<L, R> extends true
+          ? IntersectButNotEqualType<D, L, R>
+          : NotIntersect<L, R> extends true
+            ? NotIntersectType<D, L, R>
+            : never
+export type SyncRefOptions<
+  L,
+  R,
+  D extends Direction,
+> = ConfigurableFlushSync & {
+  /**
+   * Watch deeply
+   *
+   * @default false
+   */
+  deep?: boolean
+  /**
+   * Sync values immediately
+   *
+   * @default true
+   */
+  immediate?: boolean
+  /**
+   * Direction of syncing. Value will be redefined if you define syncConvertors
+   *
+   * @default 'both'
+   */
+  direction?: D
+} & TransformType<D, L, R>
+/**
+ * Two-way refs synchronization.
+ * From the set theory perspective to restrict the option's type
+ * Check in the following order:
+ * 1. L = R
+ * 2. L ∩ R ≠ ∅
+ * 3. L ⊆ R
+ * 4. L ∩ R = ∅
+ */
+export declare function syncRef<L, R, D extends Direction = "both">(
+  left: Ref<L>,
+  right: Ref<R>,
+  ...[options]: Equal<L, R> extends true
+    ? [options?: SyncRefOptions<L, R, D>]
+    : [options: SyncRefOptions<L, R, D>]
+): () => void
+```

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

@@ -0,0 +1,128 @@
+---
+category: Reactivity
+related: syncRef
+---
+
+# syncRefs
+
+Keep target refs in sync with a source ref
+
+## Usage
+
+```ts
+import { syncRefs } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const source = shallowRef('hello')
+const target = shallowRef('target')
+
+const stop = syncRefs(source, target)
+
+console.log(target.value) // hello
+
+source.value = 'foo'
+
+console.log(target.value) // foo
+```
+
+### Sync with multiple targets
+
+You can also pass an array of refs to sync.
+
+```ts
+import { syncRefs } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const source = shallowRef('hello')
+const target1 = shallowRef('target1')
+const target2 = shallowRef('target2')
+
+const stop = syncRefs(source, [target1, target2])
+
+console.log(target1.value) // hello
+console.log(target2.value) // hello
+
+source.value = 'foo'
+
+console.log(target1.value) // foo
+console.log(target2.value) // foo
+```
+
+## Watch options
+
+The options for `syncRefs` are similar to `watch`'s `WatchOptions` but with different default values.
+
+```ts
+export interface SyncRefOptions {
+  /**
+   * Timing for syncing, same as watch's flush option
+   *
+   * @default 'sync'
+   */
+  flush?: WatchOptionFlush
+  /**
+   * Watch deeply
+   *
+   * @default false
+   */
+  deep?: boolean
+  /**
+   * Sync values immediately
+   *
+   * @default true
+   */
+  immediate?: boolean
+}
+```
+
+When setting `{ flush: 'pre' }`, the target reference will be updated at [the end of the current "tick"](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing) before rendering starts.
+
+```ts
+import { syncRefs } from '@vueuse/core'
+import { nextTick, shallowRef } from 'vue'
+
+const source = shallowRef('hello')
+const target = shallowRef('target')
+
+syncRefs(source, target, { flush: 'pre' })
+
+console.log(target.value) // hello
+
+source.value = 'foo'
+
+console.log(target.value) // hello <- still unchanged, because of flush 'pre'
+
+await nextTick()
+
+console.log(target.value) // foo <- changed!
+```
+
+## Type Declarations
+
+```ts
+export interface SyncRefsOptions extends ConfigurableFlushSync {
+  /**
+   * Watch deeply
+   *
+   * @default false
+   */
+  deep?: boolean
+  /**
+   * Sync values immediately
+   *
+   * @default true
+   */
+  immediate?: boolean
+}
+/**
+ * Keep target ref(s) in sync with the source ref
+ *
+ * @param source source ref
+ * @param targets
+ */
+export declare function syncRefs<T>(
+  source: WatchSource<T>,
+  targets: Ref<T> | Ref<T>[],
+  options?: SyncRefsOptions,
+): WatchHandle
+```

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

@@ -0,0 +1,86 @@
+---
+category: Component
+---
+
+::: info
+This function will be removed in future version.
+
+Vue 3.5 introduced the `useTemplateRef` API which can effectively replace the functionality of `templateRef`, therefore we recommend using the native approach.
+:::
+
+# templateRef
+
+Shorthand for binding ref to template element.
+
+## Usage
+
+<!-- eslint-skip -->
+
+```vue
+<script lang="ts">
+import { templateRef } from '@vueuse/core'
+
+export default {
+  setup() {
+    const target = templateRef('target')
+
+    // no need to return the `target`, it will bind to the ref magically
+  },
+}
+</script>
+
+<template>
+  <div ref="target" />
+</template>
+```
+
+### With JSX/TSX
+
+```tsx
+import { templateRef } from '@vueuse/core'
+
+export default {
+  setup() {
+    const target = templateRef<HTMLElement | null>('target', null)
+
+    // use string ref
+    return () => <div ref="target"></div>
+  },
+}
+```
+
+### `<script setup>`
+
+There is no need for this when using with `<script setup>` since all the variables will be exposed to the template. It will be exactly the same as `ref`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const target = ref<HTMLElement | null>(null)
+</script>
+
+<template>
+  <div ref="target" />
+</template>
+```
+
+## Type Declarations
+
+```ts
+/**
+ * @deprecated Use Vue's built-in `useTemplateRef` instead.
+ *
+ * Shorthand for binding ref to template element.
+ *
+ * @see https://vueuse.org/templateRef
+ * @param key
+ * @param initialValue
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function templateRef<
+  T extends HTMLElement | SVGElement | Component | null,
+  Keys extends string = string,
+>(key: Keys, initialValue?: T | null): Readonly<Ref<T>>
+```

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

@@ -0,0 +1,38 @@
+---
+category: '@RxJS'
+---
+
+# toObserver
+
+Sugar function to convert a `ref` into an RxJS [Observer](https://rxjs.dev/guide/observer).
+
+## Usage
+
+<!-- TODO: import rxjs error if enable twoslash -->
+
+```ts no-twoslash
+import { from, fromEvent, toObserver, useSubscription } from '@vueuse/rxjs'
+import { interval } from 'rxjs'
+import { map, mapTo, startWith, takeUntil, withLatestFrom } from 'rxjs/operators'
+import { shallowRef, useTemplateRef } from 'vue'
+
+const count = shallowRef(0)
+const button = useTemplateRef('buttonRef')
+
+useSubscription(
+  interval(1000)
+    .pipe(
+      mapTo(1),
+      takeUntil(fromEvent(button, 'click')),
+      withLatestFrom(from(count).pipe(startWith(0))),
+      map(([curr, total]) => curr + total),
+    )
+    .subscribe(toObserver(count)), // same as ).subscribe(val => (count.value = val))
+)
+```
+
+## Type Declarations
+
+```ts
+export declare function toObserver<T>(value: Ref<T>): NextObserver<T>
+```

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

@@ -0,0 +1,41 @@
+---
+category: Reactivity
+---
+
+# toReactive
+
+Converts ref to reactive. Also made possible to create a "swapable" reactive object.
+
+## Usage
+
+```ts
+import { toReactive } from '@vueuse/core'
+import { ref } from 'vue'
+
+const refState = ref({ foo: 'bar' })
+
+console.log(refState.value.foo) // => 'bar'
+
+const state = toReactive(refState) // <--
+
+console.log(state.foo) // => 'bar'
+
+refState.value = { bar: 'foo' }
+
+console.log(state.foo) // => undefined
+console.log(state.bar) // => 'foo'
+```
+
+## Type Declarations
+
+```ts
+/**
+ * Converts ref to reactive.
+ *
+ * @see https://vueuse.org/toReactive
+ * @param objectRef A ref of object
+ */
+export declare function toReactive<T extends object>(
+  objectRef: MaybeRef<T>,
+): UnwrapNestedRefs<T>
+```

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

@@ -0,0 +1,75 @@
+---
+category: Reactivity
+alias: resolveRef
+---
+
+# toRef
+
+Normalize value/ref/getter to `ref` or `computed`.
+
+## Usage
+
+```ts
+import { toRef } from '@vueuse/core'
+
+const foo = ref('hi')
+
+const a = toRef(0) // Ref<number>
+const b = toRef(foo) // Ref<string>
+const c = toRef(() => 'hi') // ComputedRef<string>
+```
+
+## Differences from Vue's `toRef`
+
+VueUse's `toRef` is not the same as Vue’s `toRef` from the `vue` package.
+
+### VueUse `toRef`
+
+- Accepts **value**, **ref**, or **getter**
+- Returns:
+  - a **ref** for primitive values
+  - a **ref** for existing refs
+  - a **computed** for getter functions
+- Does **not** accept `object + key`
+- Getters always produce readonly computed values
+
+### Vue `toRef`
+
+- Accepts only:
+  - a **reactive object + property key**, or
+  - an existing **ref**
+- Produces a **writable ref** linked to the underlying reactive object
+- Does **not** accept primitive values
+- Does **not** accept getter functions
+
+### Summary
+
+| Behavior                 | VueUse `toRef`            | Vue `toRef`             |
+| ------------------------ | ------------------------- | ----------------------- |
+| Accepts primitive values | ✔️                        | ❌                      |
+| Accepts getter           | ✔️ (computed)             | ❌                      |
+| Accepts existing ref     | ✔️                        | ✔️                      |
+| Accepts object + key     | ❌                        | ✔️                      |
+| Writable                 | ✔️ (except getter)        | ✔️                      |
+| Purpose                  | Normalize to ref/computed | Bind to reactive object |
+
+## Type Declarations
+
+```ts
+/**
+ * Normalize value/ref/getter to `ref` or `computed`.
+ */
+export declare function toRef<T>(r: () => T): Readonly<Ref<T>>
+export declare function toRef<T>(r: ComputedRef<T>): ComputedRef<T>
+export declare function toRef<T>(r: MaybeRefOrGetter<T>): Ref<T>
+export declare function toRef<T>(r: T): Ref<T>
+export declare function toRef<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+): ToRef<T[K]>
+export declare function toRef<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+  defaultValue: T[K],
+): ToRef<Exclude<T[K], undefined>>
+```

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

@@ -0,0 +1,81 @@
+---
+category: Reactivity
+---
+
+# toRefs
+
+Extended [`toRefs`](https://vuejs.org/api/reactivity-utilities.html#torefs) that also accepts refs of an object.
+
+## Usage
+
+<!-- eslint-disable array-bracket-spacing -->
+<!-- eslint-disable ts/no-redeclare -->
+
+```ts
+import { toRefs } from '@vueuse/core'
+import { reactive, ref } from 'vue'
+
+const objRef = ref({ a: 'a', b: 0 })
+const arrRef = ref(['a', 0])
+
+const { a, b } = toRefs(objRef)
+const [a, b] = toRefs(arrRef)
+
+const obj = reactive({ a: 'a', b: 0 })
+const arr = reactive(['a', 0])
+
+const { a, b } = toRefs(obj)
+const [a, b] = toRefs(arr)
+```
+
+## Use-cases
+
+### Destructuring a props object
+
+```vue
+<script lang="ts">
+import { toRefs, useVModel } from '@vueuse/core'
+
+export default {
+  setup(props) {
+    const refs = toRefs(useVModel(props, 'data'))
+
+    console.log(refs.a.value) // props.data.a
+    refs.a.value = 'a' // emit('update:data', { ...props.data, a: 'a' })
+
+    return { ...refs }
+  }
+}
+</script>
+
+<template>
+  <div>
+    <input v-model="a" type="text">
+    <input v-model="b" type="text">
+  </div>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface ToRefsOptions {
+  /**
+   * Replace the original ref with a copy on property update.
+   *
+   * @default true
+   */
+  replaceRef?: MaybeRefOrGetter<boolean>
+}
+/**
+ * Extended `toRefs` that also accepts refs of an object.
+ *
+ * @see https://vueuse.org/toRefs
+ * @param objectRef A ref or normal object or array.
+ * @param options Options
+ */
+export declare function toRefs<T extends object>(
+  objectRef: MaybeRef<T>,
+  options?: ToRefsOptions,
+): ToRefs<T>
+```

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

@@ -0,0 +1,34 @@
+---
+category: Component
+---
+
+# tryOnBeforeMount
+
+Safe `onBeforeMount`. Call `onBeforeMount()` if it's inside a component lifecycle, if not, just call the function
+
+## Usage
+
+```ts
+import { tryOnBeforeMount } from '@vueuse/core'
+
+tryOnBeforeMount(() => {
+
+})
+```
+
+## Type Declarations
+
+```ts
+/**
+ * Call onBeforeMount() if it's inside a component lifecycle, if not, just call the function
+ *
+ * @param fn
+ * @param sync if set to false, it will run in the nextTick() of Vue
+ * @param target
+ */
+export declare function tryOnBeforeMount(
+  fn: Fn,
+  sync?: boolean,
+  target?: ComponentInternalInstance | null,
+): void
+```

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

@@ -0,0 +1,32 @@
+---
+category: Component
+---
+
+# tryOnBeforeUnmount
+
+Safe `onBeforeUnmount`. Call `onBeforeUnmount()` if it's inside a component lifecycle, if not, do nothing
+
+## Usage
+
+```ts
+import { tryOnBeforeUnmount } from '@vueuse/core'
+
+tryOnBeforeUnmount(() => {
+
+})
+```
+
+## Type Declarations
+
+```ts
+/**
+ * Call onBeforeUnmount() if it's inside a component lifecycle, if not, do nothing
+ *
+ * @param fn
+ * @param target
+ */
+export declare function tryOnBeforeUnmount(
+  fn: Fn,
+  target?: ComponentInternalInstance | null,
+): void
+```