devskill 2.0.2

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

@@ -0,0 +1,278 @@
+---
+category: State
+related: useLocalStorage, useSessionStorage, useStorageAsync
+---
+
+# useStorage
+
+Create a reactive ref that can be used to access & modify [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
+
+Uses localStorage by default, other storage sources be specified via third argument.
+
+## Usage
+
+::: tip
+When using with Nuxt 3, this function will **NOT** be auto imported in favor of Nitro's built-in [`useStorage()`](https://nitro.unjs.io/guide/storage). Use explicit import if you want to use the function from VueUse.
+:::
+
+```ts
+import { useStorage } from '@vueuse/core'
+
+// bind object
+const state = useStorage('my-store', { hello: 'hi', greeting: 'Hello' })
+
+// bind boolean
+const flag = useStorage('my-flag', true) // returns Ref<boolean>
+
+// bind number
+const count = useStorage('my-count', 0) // returns Ref<number>
+
+// bind string with SessionStorage
+const id = useStorage('my-id', 'some-string-id', sessionStorage) // returns Ref<string>
+
+// delete data from storage
+state.value = null
+```
+
+## Merge Defaults
+
+By default, `useStorage` will use the value from storage if it is present and ignores the default value. Be aware that when you are adding more properties to the default value, the key might be `undefined` if client's storage does not have that key.
+
+```ts
+import { useStorage } from '@vueuse/core'
+// ---cut---
+localStorage.setItem('my-store', '{"hello": "hello"}')
+
+const state = useStorage('my-store', { hello: 'hi', greeting: 'hello' }, localStorage)
+
+console.log(state.value.greeting) // undefined, since the value is not presented in storage
+```
+
+To solve that, you can enable `mergeDefaults` option.
+
+```ts
+import { useStorage } from '@vueuse/core'
+// ---cut---
+localStorage.setItem('my-store', '{"hello": "nihao"}')
+
+const state = useStorage(
+  'my-store',
+  { hello: 'hi', greeting: 'hello' },
+  localStorage,
+  { mergeDefaults: true } // <--
+)
+
+console.log(state.value.hello) // 'nihao', from storage
+console.log(state.value.greeting) // 'hello', from merged default value
+```
+
+When setting it to true, it will perform a **shallow merge** for objects. You can pass a function to perform custom merge (e.g. deep merge), for example:
+
+```ts
+import { useStorage } from '@vueuse/core'
+// ---cut---
+const state = useStorage(
+  'my-store',
+  { hello: 'hi', greeting: 'hello' },
+  localStorage,
+  { mergeDefaults: (storageValue, defaults) => deepMerge(defaults, storageValue) } // <--
+)
+```
+
+## Custom Serialization
+
+By default, `useStorage` will smartly use the corresponding serializer based on the data type of provided default value. For example, `JSON.stringify` / `JSON.parse` will be used for objects, `Number.toString` / `parseFloat` for numbers, etc.
+
+You can also provide your own serialization function to `useStorage`:
+
+```ts
+import { useStorage } from '@vueuse/core'
+
+useStorage(
+  'key',
+  {},
+  undefined,
+  {
+    serializer: {
+      read: (v: any) => v ? JSON.parse(v) : null,
+      write: (v: any) => JSON.stringify(v),
+    },
+  },
+)
+```
+
+Please note when you provide `null` as the default value, `useStorage` can't assume the data type from it. In this case, you can provide a custom serializer or reuse the built-in ones explicitly.
+
+```ts
+import { StorageSerializers, useStorage } from '@vueuse/core'
+
+const objectLike = useStorage('key', null, undefined, { serializer: StorageSerializers.object })
+objectLike.value = { foo: 'bar' }
+```
+
+### Built-in Serializers
+
+The following serializers are available via `StorageSerializers`:
+
+| Type      | Description                           |
+| --------- | ------------------------------------- |
+| `string`  | Plain string                          |
+| `number`  | Number (via `parseFloat`)             |
+| `boolean` | Boolean                               |
+| `object`  | JSON object/array                     |
+| `map`     | JavaScript `Map`                      |
+| `set`     | JavaScript `Set`                      |
+| `date`    | JavaScript `Date` (via `toISOString`) |
+| `any`     | Raw string passthrough                |
+
+```ts
+import { StorageSerializers, useStorage } from '@vueuse/core'
+
+const myMap = useStorage('my-map', new Map(), undefined, {
+  serializer: StorageSerializers.map,
+})
+```
+
+## Options
+
+```ts
+useStorage('key', defaults, storage, {
+  // Watch for deep changes in objects/arrays (default: true)
+  deep: true,
+  // Sync across tabs via storage events (default: true)
+  listenToStorageChanges: true,
+  // Write default value to storage if not present (default: true)
+  writeDefaults: true,
+  // Use shallowRef instead of ref (default: false)
+  shallow: false,
+  // Initialize only after component is mounted (default: false)
+  initOnMounted: false,
+  // Custom error handler (default: console.error)
+  onError: e => console.error(e),
+  // Watch flush timing (default: 'pre')
+  flush: 'pre',
+})
+```
+
+## Reactive Key
+
+The storage key can be a ref or getter, and the data will be updated when the key changes:
+
+```ts
+import { useStorage } from '@vueuse/core'
+
+const userId = ref('user-1')
+const userData = useStorage(
+  () => `user-data-${userId.value}`,
+  { name: '' },
+)
+
+// Changing the key will read from the new storage location
+userId.value = 'user-2'
+```
+
+## Type Declarations
+
+```ts
+export interface Serializer<T> {
+  read: (raw: string) => T
+  write: (value: T) => string
+}
+export interface SerializerAsync<T> {
+  read: (raw: string) => Awaitable<T>
+  write: (value: T) => Awaitable<string>
+}
+export declare const StorageSerializers: Record<
+  "boolean" | "object" | "number" | "any" | "string" | "map" | "set" | "date",
+  Serializer<any>
+>
+export declare const customStorageEventName = "vueuse-storage"
+export interface StorageEventLike {
+  storageArea: StorageLike | null
+  key: StorageEvent["key"]
+  oldValue: StorageEvent["oldValue"]
+  newValue: StorageEvent["newValue"]
+}
+export interface UseStorageOptions<T>
+  extends ConfigurableEventFilter, ConfigurableWindow, ConfigurableFlush {
+  /**
+   * Watch for deep changes
+   *
+   * @default true
+   */
+  deep?: boolean
+  /**
+   * Listen to storage changes, useful for multiple tabs application
+   *
+   * @default true
+   */
+  listenToStorageChanges?: boolean
+  /**
+   * Write the default value to the storage when it does not exist
+   *
+   * @default true
+   */
+  writeDefaults?: boolean
+  /**
+   * Merge the default value with the value read from the storage.
+   *
+   * When setting it to true, it will perform a **shallow merge** for objects.
+   * You can pass a function to perform custom merge (e.g. deep merge), for example:
+   *
+   * @default false
+   */
+  mergeDefaults?: boolean | ((storageValue: T, defaults: T) => T)
+  /**
+   * Custom data serialization
+   */
+  serializer?: Serializer<T>
+  /**
+   * On error callback
+   *
+   * Default log error to `console.error`
+   */
+  onError?: (error: unknown) => void
+  /**
+   * Use shallow ref as reference
+   *
+   * @default false
+   */
+  shallow?: boolean
+  /**
+   * Wait for the component to be mounted before reading the storage.
+   *
+   * @default false
+   */
+  initOnMounted?: boolean
+}
+export declare function useStorage(
+  key: MaybeRefOrGetter<string>,
+  defaults: MaybeRefOrGetter<string>,
+  storage?: StorageLike,
+  options?: UseStorageOptions<string>,
+): RemovableRef<string>
+export declare function useStorage(
+  key: MaybeRefOrGetter<string>,
+  defaults: MaybeRefOrGetter<boolean>,
+  storage?: StorageLike,
+  options?: UseStorageOptions<boolean>,
+): RemovableRef<boolean>
+export declare function useStorage(
+  key: MaybeRefOrGetter<string>,
+  defaults: MaybeRefOrGetter<number>,
+  storage?: StorageLike,
+  options?: UseStorageOptions<number>,
+): RemovableRef<number>
+export declare function useStorage<T>(
+  key: MaybeRefOrGetter<string>,
+  defaults: MaybeRefOrGetter<T>,
+  storage?: StorageLike,
+  options?: UseStorageOptions<T>,
+): RemovableRef<T>
+export declare function useStorage<T = unknown>(
+  key: MaybeRefOrGetter<string>,
+  defaults: MaybeRefOrGetter<null>,
+  storage?: StorageLike,
+  options?: UseStorageOptions<T>,
+): RemovableRef<T>
+```

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

@@ -0,0 +1,136 @@
+---
+category: State
+---
+
+# useStorageAsync
+
+Reactive Storage in with async support.
+
+## Usage
+
+The basic usage please refer to `useStorage`.
+
+## Wait First Loaded
+
+When user entering your app, `useStorageAsync()` will start loading value from an async storage,
+sometimes you may get the default initial value, not the real value stored in storage at the very
+beginning.
+
+```ts
+import { useStorageAsync } from '@vueuse/core'
+
+const accessToken = useStorageAsync('access.token', '', SomeAsyncStorage)
+
+// accessToken.value may be empty before the async storage is ready
+console.log(accessToken.value) // ""
+
+setTimeout(() => {
+  // After some time, the async storage is ready
+  console.log(accessToken.value) // "the real value stored in storage"
+}, 500)
+```
+
+In this case, you can wait the storage prepared, the returned value is also a `Promise`,
+so you can wait it resolved in your template or script.
+
+```ts
+// Use top-level await if your environment supports it
+const accessToken = await useStorageAsync('access.token', '', SomeAsyncStorage)
+
+console.log(accessToken.value) // "the real value stored in storage"
+```
+
+If you must wait multiple storages, put them into a `Promise.allSettled()`
+
+```ts
+router.onReady(async () => {
+  await Promise.allSettled([
+    accessToken,
+    refreshToken,
+    userData,
+  ])
+
+  app.mount('app')
+})
+```
+
+There is a callback named `onReady` in options:
+
+```ts
+import { useStorageAsync } from '@vueuse/core'
+
+// Use ES2024 Promise.withResolvers, you may use any Deferred object or EventBus to do same thing.
+const { promise, resolve } = Promise.withResolvers()
+
+const accessToken = useStorageAsync('access.token', '', SomeAsyncStorage, {
+  onReady(value) {
+    resolve(value)
+  }
+})
+
+// At main.ts
+router.onReady(async () => {
+  // Let's wait accessToken loaded
+  await promise
+
+  // Now accessToken has loaded, we can safely mount our app
+
+  app.mount('app')
+})
+```
+
+Simply use `resolve` as callback:
+
+```ts
+const accessToken = useStorageAsync('access.token', '', SomeAsyncStorage, {
+  onReady: resolve
+})
+```
+
+## Type Declarations
+
+```ts
+export interface UseStorageAsyncOptions<T> extends Omit<
+  UseStorageOptions<T>,
+  "serializer"
+> {
+  /**
+   * Custom data serialization
+   */
+  serializer?: SerializerAsync<T>
+  /**
+   * On first value loaded hook.
+   */
+  onReady?: (value: T) => void
+}
+export declare function useStorageAsync(
+  key: string,
+  initialValue: MaybeRefOrGetter<string>,
+  storage?: StorageLikeAsync,
+  options?: UseStorageAsyncOptions<string>,
+): RemovableRef<string> & Promise<RemovableRef<string>>
+export declare function useStorageAsync(
+  key: string,
+  initialValue: MaybeRefOrGetter<boolean>,
+  storage?: StorageLikeAsync,
+  options?: UseStorageAsyncOptions<boolean>,
+): RemovableRef<boolean> & Promise<RemovableRef<boolean>>
+export declare function useStorageAsync(
+  key: string,
+  initialValue: MaybeRefOrGetter<number>,
+  storage?: StorageLikeAsync,
+  options?: UseStorageAsyncOptions<number>,
+): RemovableRef<number> & Promise<RemovableRef<number>>
+export declare function useStorageAsync<T>(
+  key: string,
+  initialValue: MaybeRefOrGetter<T>,
+  storage?: StorageLikeAsync,
+  options?: UseStorageAsyncOptions<T>,
+): RemovableRef<T> & Promise<RemovableRef<T>>
+export declare function useStorageAsync<T = unknown>(
+  key: string,
+  initialValue: MaybeRefOrGetter<null>,
+  storage?: StorageLikeAsync,
+  options?: UseStorageAsyncOptions<T>,
+): RemovableRef<T> & Promise<RemovableRef<T>>
+```

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

@@ -0,0 +1,131 @@
+---
+category: Browser
+---
+
+# useStyleTag
+
+Inject reactive `style` element in head.
+
+## Usage
+
+### Basic usage
+
+Provide a CSS string, then `useStyleTag` will automatically generate an id and inject it in `<head>`.
+
+```ts
+import { useStyleTag } from '@vueuse/core'
+
+const {
+  id,
+  css,
+  load,
+  unload,
+  isLoaded,
+} = useStyleTag('.foo { margin-top: 32px; }')
+
+// Later you can modify styles
+css.value = '.foo { margin-top: 64px; }'
+```
+
+This code will be injected to `<head>`:
+
+```html
+<style id="vueuse_styletag_1">
+  .foo {
+    margin-top: 64px;
+  }
+</style>
+```
+
+### Custom ID
+
+If you need to define your own id, you can pass `id` as first argument.
+
+```ts
+import { useStyleTag } from '@vueuse/core'
+// ---cut---
+useStyleTag('.foo { margin-top: 32px; }', { id: 'custom-id' })
+```
+
+```html
+<!-- injected to <head> -->
+<style id="custom-id">
+  .foo {
+    margin-top: 32px;
+  }
+</style>
+```
+
+### Media query
+
+You can pass media attributes as last argument within object.
+
+```ts
+import { useStyleTag } from '@vueuse/core'
+// ---cut---
+useStyleTag('.foo { margin-top: 32px; }', { media: 'print' })
+```
+
+```html
+<!-- injected to <head> -->
+<style id="vueuse_styletag_1" media="print">
+  .foo {
+    margin-top: 32px;
+  }
+</style>
+```
+
+## Type Declarations
+
+```ts
+export interface UseStyleTagOptions extends ConfigurableDocument {
+  /**
+   * Media query for styles to apply
+   */
+  media?: string
+  /**
+   * Load the style immediately
+   *
+   * @default true
+   */
+  immediate?: boolean
+  /**
+   * Manual controls the timing of loading and unloading
+   *
+   * @default false
+   */
+  manual?: boolean
+  /**
+   * DOM id of the style tag
+   *
+   * @default auto-incremented
+   */
+  id?: string
+  /**
+   * Nonce value for CSP (Content Security Policy)
+   *
+   * @default undefined
+   */
+  nonce?: string
+}
+export interface UseStyleTagReturn {
+  id: string
+  css: ShallowRef<string>
+  load: () => void
+  unload: () => void
+  isLoaded: Readonly<ShallowRef<boolean>>
+}
+/**
+ * Inject <style> element in head.
+ *
+ * Overload: Omitted id
+ *
+ * @see https://vueuse.org/useStyleTag
+ * @param css
+ * @param options
+ */
+export declare function useStyleTag(
+  css: MaybeRef<string>,
+  options?: UseStyleTagOptions,
+): UseStyleTagReturn
+```

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

@@ -0,0 +1,77 @@
+---
+category: '@RxJS'
+---
+
+# useSubject
+
+Bind an RxJS [`Subject`](https://rxjs.dev/guide/subject) to a `ref` and propagate value changes both ways.
+
+## Usage
+
+<!-- TODO: import rxjs error if enable twoslash -->
+
+```ts no-twoslash
+import { useSubject } from '@vueuse/rxjs'
+import { Subject } from 'rxjs'
+
+const subject = new Subject()
+
+// setup()
+const subjectRef = useSubject(subject)
+
+// Changes to subjectRef.value will be pushed to the subject
+subjectRef.value = 'new value'
+
+// Values emitted by the subject will update subjectRef
+subject.next('from subject')
+```
+
+### With BehaviorSubject
+
+When using a `BehaviorSubject`, the returned ref is initialized with the subject's current value and the type does not include `undefined`:
+
+```ts no-twoslash
+import { useSubject } from '@vueuse/rxjs'
+import { BehaviorSubject } from 'rxjs'
+
+const subject = new BehaviorSubject('initial')
+
+// setup()
+const subjectRef = useSubject(subject) // Ref<string>, not Ref<string | undefined>
+console.log(subjectRef.value) // 'initial'
+```
+
+### Error Handling
+
+If you want to add custom error handling to a Subject that might error, you can supply an optional `onError` configuration. Without this, RxJS will treat any error in the supplied observable as an "unhandled error" and it will be thrown in a new call stack and reported to `window.onerror` (or `process.on('error')` if you happen to be in node).
+
+```ts no-twoslash
+import { useSubject } from '@vueuse/rxjs'
+import { Subject } from 'rxjs'
+
+const subject = new Subject()
+
+// setup()
+const subjectRef = useSubject(subject, {
+  onError: (err) => {
+    console.log(err.message) // "oops"
+  },
+},)
+```
+
+## Type Declarations
+
+```ts
+export interface UseSubjectOptions<I = undefined> extends Omit<
+  UseObservableOptions<I>,
+  "initialValue"
+> {}
+export declare function useSubject<H>(
+  subject: BehaviorSubject<H>,
+  options?: UseSubjectOptions,
+): Ref<H>
+export declare function useSubject<H>(
+  subject: Subject<H>,
+  options?: UseSubjectOptions,
+): Ref<H | undefined>
+```

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

@@ -0,0 +1,33 @@
+---
+category: '@RxJS'
+---
+
+# useSubscription
+
+Use an RxJS [`Subscription`](https://rxjs.dev/guide/subscription) without worrying about unsubscribing from it or creating memory leaks.
+
+## Usage
+
+<!-- TODO: import rxjs error if enable twoslash -->
+
+```ts no-twoslash
+import { useSubscription } from '@vueuse/rxjs'
+import { interval } from 'rxjs'
+
+const count = ref(0)
+
+// useSubscription call unsubscribe method before unmount the component
+useSubscription(
+  interval(1000)
+    .subscribe(() => {
+      count.value++
+      console.log(count)
+    }),
+)
+```
+
+## Type Declarations
+
+```ts
+export declare function useSubscription(subscription: Unsubscribable): void
+```

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

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