devskill 2.0.2

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

@@ -0,0 +1,245 @@
+---
+category: Sensors
+---
+
+# useMagicKeys
+
+Reactive keys pressed state, with magical keys combination support.
+
+## Usage
+
+```ts
+import { useMagicKeys } from '@vueuse/core'
+
+const { shift, space, a /* keys you want to monitor */ } = useMagicKeys()
+
+watch(space, (v) => {
+  if (v)
+    console.log('space has been pressed')
+})
+
+watchEffect(() => {
+  if (shift.value && a.value)
+    console.log('Shift + A have been pressed')
+})
+```
+
+::: tip NOTE
+If you're using TypeScript with `noUncheckedIndexedAccess` enabled in your `tsconfig.json` (or using Nuxt which enables it by default), the destructured keys will have the type `ComputedRef<boolean> | undefined`.
+
+The `noUncheckedIndexedAccess` TypeScript option adds `undefined` to any un-declared field accessed via index signatures. Since `useMagicKeys()` uses an index signature to allow accessing any key dynamically, TypeScript will treat destructured properties as potentially undefined for type safety.
+
+You'll need to use optional chaining or wrap with a getter function:
+
+```ts
+const { shift, space, a } = useMagicKeys()
+
+watch(
+  () => space?.value,
+  (v) => {
+    if (v)
+      console.log('space has been pressed')
+  },
+)
+
+watchEffect(() => {
+  if (shift?.value && a?.value)
+    console.log('Shift + A have been pressed')
+})
+```
+
+Check the [TypeScript documentation](https://www.typescriptlang.org/tsconfig/#noUncheckedIndexedAccess) for more details about `noUncheckedIndexedAccess`.
+
+:::
+
+Check out [all the possible keycodes](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values).
+
+### Combinations
+
+You can magically use combinations (shortcuts/hotkeys) by connecting keys with `+` or `_`.
+
+```ts
+import { useMagicKeys } from '@vueuse/core'
+
+const keys = useMagicKeys()
+const shiftCtrlA = keys['Shift+Ctrl+A']
+
+watch(shiftCtrlA, (v) => {
+  if (v)
+    console.log('Shift + Ctrl + A have been pressed')
+})
+```
+
+```ts
+import { useMagicKeys } from '@vueuse/core'
+
+const { Ctrl_A_B, space, alt_s /* ... */ } = useMagicKeys()
+
+watch(Ctrl_A_B, (v) => {
+  if (v)
+    console.log('Control+A+B have been pressed')
+})
+```
+
+You can also use `whenever` function to make it shorter
+
+```ts
+import { useMagicKeys, whenever } from '@vueuse/core'
+
+const keys = useMagicKeys()
+
+whenever(keys.shift_space, () => {
+  console.log('Shift+Space have been pressed')
+})
+```
+
+### Current Pressed keys
+
+A special property `current` is provided to representing all the keys been pressed currently.
+
+```ts
+import { useMagicKeys, whenever } from '@vueuse/core'
+
+const { current } = useMagicKeys()
+
+console.log(current) // Set { 'control', 'a' }
+
+whenever(
+  () => current.has('a') && !current.has('b'),
+  () => console.log('A is pressed but not B'),
+)
+```
+
+### Key Aliasing
+
+```ts
+import { useMagicKeys, whenever } from '@vueuse/core'
+
+const { shift_cool } = useMagicKeys({
+  aliasMap: {
+    cool: 'space',
+  },
+})
+
+whenever(shift_cool, () => console.log('Shift + Space have been pressed'))
+```
+
+By default, we have some [preconfigured alias for common practices](https://github.com/vueuse/vueuse/blob/main/packages/core/useMagicKeys/aliasMap.ts).
+
+### Conditionally Disable
+
+You might have some `<input />` elements in your apps, and you don't want to trigger the magic keys handling when users focused on those inputs. There is an example of using `useActiveElement` and `logicAnd` to do that.
+
+```ts
+import { useActiveElement, useMagicKeys, whenever } from '@vueuse/core'
+import { logicAnd } from '@vueuse/math'
+
+const activeElement = useActiveElement()
+const notUsingInput = computed(() =>
+  activeElement.value?.tagName !== 'INPUT'
+  && activeElement.value?.tagName !== 'TEXTAREA',)
+
+const { tab } = useMagicKeys()
+
+whenever(logicAnd(tab, notUsingInput), () => {
+  console.log('Tab has been pressed outside of inputs!')
+})
+```
+
+### Custom Event Handler
+
+```ts
+import { useMagicKeys, whenever } from '@vueuse/core'
+
+const { ctrl_s } = useMagicKeys({
+  passive: false,
+  onEventFired(e) {
+    if (e.ctrlKey && e.key === 's' && e.type === 'keydown')
+      e.preventDefault()
+  },
+})
+
+whenever(ctrl_s, () => console.log('Ctrl+S have been pressed'))
+```
+
+> ⚠️ This usage is NOT recommended, please use with caution.
+
+### Reactive Mode
+
+By default, the values of `useMagicKeys()` are `Ref<boolean>`. If you want to use the object in the template, you can set it to reactive mode.
+
+```ts
+import { useMagicKeys } from '@vueuse/core'
+// ---cut---
+const keys = useMagicKeys({ reactive: true })
+```
+
+```vue
+<template>
+  <div v-if="keys.shift">
+    You are holding the Shift key!
+  </div>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseMagicKeysOptions<Reactive extends boolean> {
+  /**
+   * Returns a reactive object instead of an object of refs
+   *
+   * @default false
+   */
+  reactive?: Reactive
+  /**
+   * Target for listening events
+   *
+   * @default window
+   */
+  target?: MaybeRefOrGetter<EventTarget>
+  /**
+   * Alias map for keys, all the keys should be lowercase
+   * { target: keycode }
+   *
+   * @example { ctrl: "control" }
+   * @default <predefined-map>
+   */
+  aliasMap?: Record<string, string>
+  /**
+   * Register passive listener
+   *
+   * @default true
+   */
+  passive?: boolean
+  /**
+   * Custom event handler for keydown/keyup event.
+   * Useful when you want to apply custom logic.
+   *
+   * When using `e.preventDefault()`, you will need to pass `passive: false` to useMagicKeys().
+   */
+  onEventFired?: (e: KeyboardEvent) => void | boolean
+}
+export interface MagicKeysInternal {
+  /**
+   * A Set of currently pressed keys,
+   * Stores raw keyCodes.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key
+   */
+  current: Set<string>
+}
+export type UseMagicKeysReturn<Reactive extends boolean> = Readonly<
+  Record<string, Reactive extends true ? boolean : ComputedRef<boolean>> &
+    MagicKeysInternal
+>
+/**
+ * Reactive keys pressed state, with magical keys combination support.
+ *
+ * @see https://vueuse.org/useMagicKeys
+ */
+export declare function useMagicKeys<T extends boolean = false>(
+  options?: UseMagicKeysOptions<T>,
+): UseMagicKeysReturn<T>
+export { DefaultMagicKeysAliasMap } from "./aliasMap"
+```

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 using 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: Ref<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>
+```