ads-fe 0.0.1

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

@@ -0,0 +1,90 @@
+---
+category: Array
+---
+
+# useSorted
+
+reactive sort array
+
+## Usage
+
+```ts
+import { useSorted } from '@vueuse/core'
+
+// general sort
+const source = [10, 3, 5, 7, 2, 1, 8, 6, 9, 4]
+const sorted = useSorted(source)
+console.log(sorted.value) // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+console.log(source) // [10, 3, 5, 7, 2, 1, 8, 6, 9, 4]
+
+// object sort
+const objArr = [{
+  name: 'John',
+  age: 40,
+}, {
+  name: 'Jane',
+  age: 20,
+}, {
+  name: 'Joe',
+  age: 30,
+}, {
+  name: 'Jenny',
+  age: 22,
+}]
+const objSorted = useSorted(objArr, (a, b) => a.age - b.age)
+```
+
+### dirty mode
+
+dirty mode will change the source array.
+
+```ts
+const source = ref([10, 3, 5, 7, 2, 1, 8, 6, 9, 4])
+const sorted = useSorted(source, (a, b) => a - b, {
+  dirty: true,
+})
+console.log(source)// output: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+```
+
+## Type Declarations
+
+```ts
+export type UseSortedCompareFn<T = any> = (a: T, b: T) => number
+export type UseSortedFn<T = any> = (
+  arr: T[],
+  compareFn: UseSortedCompareFn<T>,
+) => T[]
+export interface UseSortedOptions<T = any> {
+  /**
+   * sort algorithm
+   */
+  sortFn?: UseSortedFn<T>
+  /**
+   * compare function
+   */
+  compareFn?: UseSortedCompareFn<T>
+  /**
+   * change the value of the source array
+   * @default false
+   */
+  dirty?: boolean
+}
+/**
+ * reactive sort array
+ *
+ * @see https://vueuse.org/useSorted
+ */
+export declare function useSorted<T = any>(
+  source: MaybeRefOrGetter<T[]>,
+  compareFn?: UseSortedCompareFn<T>,
+): Ref<T[]>
+export declare function useSorted<T = any>(
+  source: MaybeRefOrGetter<T[]>,
+  options?: UseSortedOptions<T>,
+): Ref<T[]>
+export declare function useSorted<T = any>(
+  source: MaybeRefOrGetter<T[]>,
+  compareFn?: UseSortedCompareFn<T>,
+  options?: Omit<UseSortedOptions<T>, "compareFn">,
+): Ref<T[]>
+```

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

@@ -0,0 +1,90 @@
+---
+category: Sensors
+---
+
+# useSpeechRecognition
+
+Reactive [SpeechRecognition](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition).
+
+> [Can I use?](https://caniuse.com/mdn-api_speechrecognitionevent)
+
+## Usage
+
+```ts
+import { useSpeechRecognition } from '@vueuse/core'
+
+const {
+  isSupported,
+  isListening,
+  isFinal,
+  result,
+  start,
+  stop,
+} = useSpeechRecognition()
+```
+
+### Options
+
+The following shows the default values of the options, they will be directly passed to [SpeechRecognition API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition).
+
+```ts
+import { useSpeechRecognition } from '@vueuse/core'
+// ---cut---
+useSpeechRecognition({
+  lang: 'en-US',
+  interimResults: true,
+  continuous: true,
+})
+```
+
+## Type Declarations
+
+```ts
+export interface UseSpeechRecognitionOptions extends ConfigurableWindow {
+  /**
+   * Controls whether continuous results are returned for each recognition, or only a single result.
+   *
+   * @default true
+   */
+  continuous?: boolean
+  /**
+   * Controls whether interim results should be returned (true) or not (false.) Interim results are results that are not yet final
+   *
+   * @default true
+   */
+  interimResults?: boolean
+  /**
+   * Language for SpeechRecognition
+   *
+   * @default 'en-US'
+   */
+  lang?: MaybeRefOrGetter<string>
+  /**
+   * A number representing the maximum returned alternatives for each result.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/maxAlternatives
+   * @default 1
+   */
+  maxAlternatives?: number
+}
+export interface UseSpeechRecognitionReturn extends Supportable {
+  isListening: ShallowRef<boolean>
+  isFinal: ShallowRef<boolean>
+  recognition: SpeechRecognition | undefined
+  result: ShallowRef<string>
+  error: ShallowRef<SpeechRecognitionErrorEvent | Error | undefined>
+  toggle: (value?: boolean) => void
+  start: () => void
+  stop: () => void
+}
+/**
+ * Reactive SpeechRecognition.
+ *
+ * @see https://vueuse.org/useSpeechRecognition
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition SpeechRecognition
+ * @param options
+ */
+export declare function useSpeechRecognition(
+  options?: UseSpeechRecognitionOptions,
+): UseSpeechRecognitionReturn
+```

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

@@ -0,0 +1,101 @@
+---
+category: Sensors
+---
+
+# useSpeechSynthesis
+
+Reactive [SpeechSynthesis](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis).
+
+> [Can I use?](https://caniuse.com/mdn-api_speechsynthesis)
+
+## Usage
+
+```ts
+import { useSpeechSynthesis } from '@vueuse/core'
+
+const {
+  isSupported,
+  isPlaying,
+  status,
+  voiceInfo,
+  utterance,
+  error,
+  stop,
+  toggle,
+  speak,
+} = useSpeechSynthesis()
+```
+
+### Options
+
+The following shows the default values of the options, they will be directly passed to [SpeechSynthesis API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis).
+
+```ts
+import { useSpeechSynthesis } from '@vueuse/core'
+// ---cut---
+useSpeechSynthesis({
+  lang: 'en-US',
+  pitch: 1,
+  rate: 1,
+  volume: 1,
+})
+```
+
+## Type Declarations
+
+```ts
+export type UseSpeechSynthesisStatus = "init" | "play" | "pause" | "end"
+export interface UseSpeechSynthesisOptions extends ConfigurableWindow {
+  /**
+   * Language for SpeechSynthesis
+   *
+   * @default 'en-US'
+   */
+  lang?: MaybeRefOrGetter<string>
+  /**
+   * Gets and sets the pitch at which the utterance will be spoken at.
+   *
+   * @default 1
+   */
+  pitch?: MaybeRefOrGetter<SpeechSynthesisUtterance["pitch"]>
+  /**
+   * Gets and sets the speed at which the utterance will be spoken at.
+   *
+   * @default 1
+   */
+  rate?: MaybeRefOrGetter<SpeechSynthesisUtterance["rate"]>
+  /**
+   * Gets and sets the voice that will be used to speak the utterance.
+   */
+  voice?: MaybeRef<SpeechSynthesisVoice>
+  /**
+   * Gets and sets the volume that the utterance will be spoken at.
+   *
+   * @default 1
+   */
+  volume?: MaybeRefOrGetter<SpeechSynthesisUtterance["volume"]>
+  /**
+   * Callback function that is called when the boundary event is triggered.
+   */
+  onBoundary?: (event: SpeechSynthesisEvent) => void
+}
+export interface UseSpeechSynthesisReturn extends Supportable {
+  isPlaying: ShallowRef<boolean>
+  status: ShallowRef<UseSpeechSynthesisStatus>
+  utterance: ComputedRef<SpeechSynthesisUtterance>
+  error: ShallowRef<SpeechSynthesisErrorEvent | undefined>
+  stop: () => void
+  toggle: (value?: boolean) => void
+  speak: () => void
+}
+/**
+ * Reactive SpeechSynthesis.
+ *
+ * @see https://vueuse.org/useSpeechSynthesis
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis SpeechSynthesis
+ */
+export declare function useSpeechSynthesis(
+  text: MaybeRefOrGetter<string>,
+  options?: UseSpeechSynthesisOptions,
+): UseSpeechSynthesisReturn
+```

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

@@ -0,0 +1,137 @@
+---
+category: Utilities
+---
+
+# useStepper
+
+Provides helpers for building a multi-step wizard interface.
+
+## Usage
+
+### Steps as array
+
+```ts
+import { useStepper } from '@vueuse/core'
+
+const {
+  steps,
+  stepNames,
+  index,
+  current,
+  next,
+  previous,
+  isFirst,
+  isLast,
+  goTo,
+  goToNext,
+  goToPrevious,
+  goBackTo,
+  isNext,
+  isPrevious,
+  isCurrent,
+  isBefore,
+  isAfter,
+} = useStepper([
+  'billing-address',
+  'terms',
+  'payment',
+])
+
+// Access the step through `current`
+console.log(current.value) // 'billing-address'
+```
+
+### Steps as object
+
+```ts
+import { useStepper } from '@vueuse/core'
+
+const {
+  steps,
+  stepNames,
+  index,
+  current,
+  next,
+  previous,
+  isFirst,
+  isLast,
+  goTo,
+  goToNext,
+  goToPrevious,
+  goBackTo,
+  isNext,
+  isPrevious,
+  isCurrent,
+  isBefore,
+  isAfter,
+} = useStepper({
+  'user-information': {
+    title: 'User information',
+  },
+  'billing-address': {
+    title: 'Billing address',
+  },
+  'terms': {
+    title: 'Terms',
+  },
+  'payment': {
+    title: 'Payment',
+  },
+})
+
+// Access the step object through `current`
+console.log(current.value.title) // 'User information'
+```
+
+## Type Declarations
+
+```ts
+export interface UseStepperReturn<StepName, Steps, Step> {
+  /** List of steps. */
+  steps: Readonly<Ref<Steps>>
+  /** List of step names. */
+  stepNames: Readonly<Ref<StepName[]>>
+  /** Index of the current step. */
+  index: Ref<number>
+  /** Current step. */
+  current: ComputedRef<Step>
+  /** Next step, or undefined if the current step is the last one. */
+  next: ComputedRef<StepName | undefined>
+  /** Previous step, or undefined if the current step is the first one. */
+  previous: ComputedRef<StepName | undefined>
+  /** Whether the current step is the first one. */
+  isFirst: ComputedRef<boolean>
+  /** Whether the current step is the last one. */
+  isLast: ComputedRef<boolean>
+  /** Get the step at the specified index. */
+  at: (index: number) => Step | undefined
+  /** Get a step by the specified name. */
+  get: (step: StepName) => Step | undefined
+  /** Go to the specified step. */
+  goTo: (step: StepName) => void
+  /** Go to the next step. Does nothing if the current step is the last one. */
+  goToNext: () => void
+  /** Go to the previous step. Does nothing if the current step is the previous one. */
+  goToPrevious: () => void
+  /** Go back to the given step, only if the current step is after. */
+  goBackTo: (step: StepName) => void
+  /** Checks whether the given step is the next step. */
+  isNext: (step: StepName) => boolean
+  /** Checks whether the given step is the previous step. */
+  isPrevious: (step: StepName) => boolean
+  /** Checks whether the given step is the current step. */
+  isCurrent: (step: StepName) => boolean
+  /** Checks if the current step is before the given step. */
+  isBefore: (step: StepName) => boolean
+  /** Checks if the current step is after the given step. */
+  isAfter: (step: StepName) => boolean
+}
+export declare function useStepper<T extends string | number>(
+  steps: MaybeRef<T[]>,
+  initialStep?: T,
+): UseStepperReturn<T, T[], T>
+export declare function useStepper<T extends Record<string, any>>(
+  steps: MaybeRef<T>,
+  initialStep?: keyof T,
+): UseStepperReturn<Exclude<keyof T, symbol>, T, T[keyof T]>
+```

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>
+```