aico-cli 2.1.7 → 2.1.23

package/templates/skills/vueuse-functions/references/useCounter.md

@@ -0,0 +1,86 @@
+---
+category: Utilities
+---
+
+# useCounter
+
+Basic counter with utility functions.
+
+## Basic Usage
+
+```ts
+import { useCounter } from '@vueuse/core'
+
+const { count, inc, dec, set, reset } = useCounter()
+```
+
+## Usage with options
+
+```ts
+import { useCounter } from '@vueuse/core'
+
+const { count, inc, dec, set, reset } = useCounter(1, { min: 0, max: 16 })
+```
+
+## Type Declarations
+
+```ts
+export interface UseCounterOptions {
+  min?: number
+  max?: number
+}
+export interface UseCounterReturn {
+  /**
+   * The current value of the counter.
+   */
+  readonly count: Readonly<Ref<number>>
+  /**
+   * Increment the counter.
+   *
+   * @param {number} [delta=1] The number to increment.
+   */
+  inc: (delta?: number) => void
+  /**
+   * Decrement the counter.
+   *
+   * @param {number} [delta=1] The number to decrement.
+   */
+  dec: (delta?: number) => void
+  /**
+   * Get the current value of the counter.
+   */
+  get: () => number
+  /**
+   * Set the counter to a new value.
+   *
+   * @param val The new value of the counter.
+   */
+  set: (val: number) => void
+  /**
+   * Reset the counter to an initial value.
+   */
+  reset: (val?: number) => number
+}
+/**
+ * Basic counter with utility functions.
+ *
+ * @see https://vueuse.org/useCounter
+ * @param [initialValue]
+ * @param options
+ */
+export declare function useCounter(
+  initialValue?: MaybeRef<number>,
+  options?: UseCounterOptions,
+): {
+  count: Readonly<
+    | Ref<number, number>
+    | ShallowRef<number, number>
+    | WritableComputedRef<number, number>
+  >
+  inc: (delta?: number) => number
+  dec: (delta?: number) => number
+  get: () => number
+  set: (val: number) => number
+  reset: (val?: number) => number
+}
+```

package/templates/skills/vueuse-functions/references/useCssVar.md

@@ -0,0 +1,50 @@
+---
+category: Browser
+---
+
+# useCssVar
+
+Manipulate CSS variables
+
+## Usage
+
+```ts
+import { useCssVar } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const color1 = useCssVar('--color', el)
+
+const elv = useTemplateRef('elv')
+const key = ref('--color')
+const colorVal = useCssVar(key, elv)
+
+const someEl = useTemplateRef('someEl')
+const color2 = useCssVar('--color', someEl, { initialValue: '#eee' })
+```
+
+## Type Declarations
+
+```ts
+export interface UseCssVarOptions extends ConfigurableWindow {
+  initialValue?: string
+  /**
+   * Use MutationObserver to monitor variable changes
+   * @default false
+   */
+  observe?: boolean
+}
+/**
+ * Manipulate CSS variables.
+ *
+ * @see https://vueuse.org/useCssVar
+ * @param prop
+ * @param target
+ * @param options
+ */
+export declare function useCssVar(
+  prop: MaybeRefOrGetter<string | null | undefined>,
+  target?: MaybeElementRef,
+  options?: UseCssVarOptions,
+): ShallowRef<string | undefined, string | undefined>
+```

package/templates/skills/vueuse-functions/references/useCurrentElement.md

@@ -0,0 +1,61 @@
+---
+category: Component
+---
+
+# useCurrentElement
+
+Get the DOM element of current component as a ref.
+
+## Usage
+
+```ts
+import { useCurrentElement } from '@vueuse/core'
+
+const el = useCurrentElement() // ComputedRef<Element>
+```
+
+Or pass a specific vue component
+
+```vue
+<script setup lang="ts">
+import { useCurrentElement, VueInstance } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const componentRef = shallowRef<VueInstance>(null as unknown as VueInstance)
+
+const el = useCurrentElement(componentRef) // ComputedRef<Element>
+</script>
+
+<template>
+  <div>
+    <OtherVueComponent ref="componentRef" />
+    <p>Hello world</p>
+  </div>
+</template>
+```
+
+## Caveats
+
+This functions uses [`$el` under the hood](https://vuejs.org/api/component-instance.html#el).
+
+Value of the ref will be `undefined` until the component is mounted.
+
+- For components with a single root element, it will point to that element.
+- For components with text root, it will point to the text node.
+- For components with multiple root nodes, it will be the placeholder DOM node that Vue uses to keep track of the component's position in the DOM.
+
+It's recommend to only use this function for components with **a single root element**.
+
+## Type Declarations
+
+```ts
+export declare function useCurrentElement<
+  T extends MaybeElement = MaybeElement,
+  R extends VueInstance = VueInstance,
+  E extends MaybeElement = MaybeElement extends T
+    ? IsAny<R["$el"]> extends false
+      ? R["$el"]
+      : T
+    : T,
+>(rootComponent?: MaybeElementRef<R>): ComputedRefWithControl<E>
+```

package/templates/skills/vueuse-functions/references/useCycleList.md

@@ -0,0 +1,75 @@
+---
+category: Utilities
+---
+
+# useCycleList
+
+Cycle through a list of items.
+
+<CourseLink href="https://vueschool.io/lessons/create-an-image-carousel-with-vueuse?friend=vueuse">Learn how to use useCycleList to create an image carousel with this FREE video lesson from Vue School!</CourseLink>
+
+## Usage
+
+```ts
+import { useCycleList } from '@vueuse/core'
+
+const { state, next, prev, go } = useCycleList([
+  'Dog',
+  'Cat',
+  'Lizard',
+  'Shark',
+  'Whale',
+  'Dolphin',
+  'Octopus',
+  'Seal',
+])
+
+console.log(state.value) // 'Dog'
+
+prev()
+
+console.log(state.value) // 'Seal'
+
+go(3)
+
+console.log(state.value) // 'Shark'
+```
+
+## Type Declarations
+
+```ts
+export interface UseCycleListOptions<T> {
+  /**
+   * The initial value of the state.
+   * A ref can be provided to reuse.
+   */
+  initialValue?: MaybeRef<T>
+  /**
+   * The default index when
+   */
+  fallbackIndex?: number
+  /**
+   * Custom function to get the index of the current value.
+   */
+  getIndexOf?: (value: T, list: T[]) => number
+}
+/**
+ * Cycle through a list of items
+ *
+ * @see https://vueuse.org/useCycleList
+ */
+export declare function useCycleList<T>(
+  list: MaybeRefOrGetter<T[]>,
+  options?: UseCycleListOptions<T>,
+): UseCycleListReturn<T>
+export interface UseCycleListReturn<T> {
+  state: ShallowRef<T>
+  index: WritableComputedRef<number>
+  next: (n?: number) => T
+  prev: (n?: number) => T
+  /**
+   * Go to a specific index
+   */
+  go: (i: number) => T
+}
+```

package/templates/skills/vueuse-functions/references/useDark.md

@@ -0,0 +1,142 @@
+---
+category: Browser
+related:
+  - useColorMode
+  - usePreferredDark
+  - useStorage
+---
+
+# useDark
+
+Reactive dark mode with auto data persistence.
+
+<CourseLink href="https://vueschool.io/lessons/theming-with-vueuse-usedark-and-usecolormode?friend=vueuse">Learn useDark with this FREE video lesson from Vue School!</CourseLink>
+
+## Basic Usage
+
+```ts
+import { useDark, useToggle } from '@vueuse/core'
+
+const isDark = useDark()
+const toggleDark = useToggle(isDark)
+```
+
+## Behavior
+
+`useDark` combines with `usePreferredDark` and `useStorage`. On start up, it reads the value from localStorage/sessionStorage (the key is configurable) to see if there is a user configured color scheme, if not, it will use users' system preferences. When you change the `isDark` ref, it will update the corresponding element's attribute and then store the preference to storage (default key: `vueuse-color-scheme`) for persistence.
+
+> Please note `useDark` only handles the DOM attribute changes for you to apply proper selector in your CSS. It does NOT handle the actual style, theme or CSS for you.
+
+## Configuration
+
+By default, it uses [Tailwind CSS favored dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually), which enables dark mode when class `dark` is applied to the `html` tag, for example:
+
+```html
+<!--light-->
+<html>
+  ...
+</html>
+
+<!--dark-->
+<html class="dark">
+  ...
+</html>
+```
+
+Still, you can also customize it to make it work with most CSS frameworks.
+
+For example:
+
+```ts
+import { useDark } from '@vueuse/core'
+// ---cut---
+const isDark = useDark({
+  selector: 'body',
+  attribute: 'color-scheme',
+  valueDark: 'dark',
+  valueLight: 'light',
+})
+```
+
+will work like
+
+```html
+<!--light-->
+<html>
+  <body color-scheme="light">
+    ...
+  </body>
+</html>
+
+<!--dark-->
+<html>
+  <body color-scheme="dark">
+    ...
+  </body>
+</html>
+```
+
+If the configuration above still does not fit your needs, you can use the`onChanged` option to take full control over how you handle updates.
+
+```ts
+import { useDark } from '@vueuse/core'
+// ---cut---
+const isDark = useDark({
+  onChanged(dark) {
+    // update the dom, call the API or something
+  },
+})
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseDark v-slot="{ isDark, toggleDark }">
+    <button @click="toggleDark()">
+      Is Dark: {{ isDark }}
+    </button>
+  </UseDark>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseDarkOptions
+  extends Omit<UseColorModeOptions<BasicColorSchema>, "modes" | "onChanged"> {
+  /**
+   * Value applying to the target element when isDark=true
+   *
+   * @default 'dark'
+   */
+  valueDark?: string
+  /**
+   * Value applying to the target element when isDark=false
+   *
+   * @default ''
+   */
+  valueLight?: string
+  /**
+   * A custom handler for handle the updates.
+   * When specified, the default behavior will be overridden.
+   *
+   * @default undefined
+   */
+  onChanged?: (
+    isDark: boolean,
+    defaultHandler: (mode: BasicColorSchema) => void,
+    mode: BasicColorSchema,
+  ) => void
+}
+/**
+ * Reactive dark mode with auto data persistence.
+ *
+ * @see https://vueuse.org/useDark
+ * @param options
+ */
+export declare function useDark(
+  options?: UseDarkOptions,
+): WritableComputedRef<boolean, boolean>
+export type UseDarkReturn = ReturnType<typeof useDark>
+```

package/templates/skills/vueuse-functions/references/useDateFormat.md

@@ -0,0 +1,145 @@
+---
+category: Time
+---
+
+# useDateFormat
+
+Get the formatted date according to the string of tokens passed in, inspired
+by [dayjs](https://github.com/iamkun/dayjs).
+
+**List of all available formats (HH:mm:ss by default):**
+
+| Format | Output                   | Description                             |
+| ------ | ------------------------ | --------------------------------------- |
+| `Yo`   | 2018th                   | Ordinal formatted year                  |
+| `YY`   | 18                       | Two-digit year                          |
+| `YYYY` | 2018                     | Four-digit year                         |
+| `M`    | 1-12                     | The month, beginning at 1               |
+| `Mo`   | 1st, 2nd, ..., 12th      | The month, ordinal formatted            |
+| `MM`   | 01-12                    | The month, 2-digits                     |
+| `MMM`  | Jan-Dec                  | The abbreviated month name              |
+| `MMMM` | January-December         | The full month name                     |
+| `D`    | 1-31                     | The day of the month                    |
+| `Do`   | 1st, 2nd, ..., 31st      | The day of the month, ordinal formatted |
+| `DD`   | 01-31                    | The day of the month, 2-digits          |
+| `H`    | 0-23                     | The hour                                |
+| `Ho`   | 0th, 1st, 2nd, ..., 23rd | The hour, ordinal formatted             |
+| `HH`   | 00-23                    | The hour, 2-digits                      |
+| `h`    | 1-12                     | The hour, 12-hour clock                 |
+| `ho`   | 1st, 2nd, ..., 12th      | The hour, 12-hour clock, sorted         |
+| `hh`   | 01-12                    | The hour, 12-hour clock, 2-digits       |
+| `m`    | 0-59                     | The minute                              |
+| `mo`   | 0th, 1st, ..., 59th      | The minute, ordinal formatted           |
+| `mm`   | 00-59                    | The minute, 2-digits                    |
+| `s`    | 0-59                     | The second                              |
+| `so`   | 0th, 1st, ..., 59th      | The second, ordinal formatted           |
+| `ss`   | 00-59                    | The second, 2-digits                    |
+| `SSS`  | 000-999                  | The millisecond, 3-digits               |
+| `A`    | AM PM                    | The meridiem                            |
+| `AA`   | A.M. P.M.                | The meridiem, periods                   |
+| `a`    | am pm                    | The meridiem, lowercase                 |
+| `aa`   | a.m. p.m.                | The meridiem, lowercase and periods     |
+| `d`    | 0-6                      | The day of the week, with Sunday as 0   |
+| `dd`   | S-S                      | The min name of the day of the week     |
+| `ddd`  | Sun-Sat                  | The short name of the day of the week   |
+| `dddd` | Sunday-Saturday          | The name of the day of the week         |
+| `z`    | GMT, GMT+1               | The timezone with offset                |
+| `zz`   | GMT, GMT+1               | The timezone with offset                |
+| `zzz`  | GMT, GMT+1               | The timezone with offset                |
+| `zzzz` | GMT, GMT+01:00           | The long timezone with offset           |
+
+- Meridiem is customizable by defining `customMeridiem` in `options`.
+
+## Usage
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from '@vueuse/core'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD HH:mm:ss')
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with locales
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from '@vueuse/core'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD (ddd)', { locales: 'en-US' })
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with custom meridiem
+
+```vue
+<script setup lang="ts">
+import { useDateFormat } from '@vueuse/core'
+
+function customMeridiem(hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) {
+  const m = hours > 11 ? (isLowercase ? 'μμ' : 'ΜΜ') : (isLowercase ? 'πμ' : 'ΠΜ')
+  return hasPeriod ? m.split('').reduce((acc, current) => acc += `${current}.`, '') : m
+}
+
+const am = useDateFormat('2022-01-01 05:05:05', 'hh:mm:ss A', { customMeridiem })
+// am.value = '05:05:05 ΠΜ'
+const pm = useDateFormat('2022-01-01 17:05:05', 'hh:mm:ss AA', { customMeridiem })
+// pm.value = '05:05:05 Μ.Μ.'
+</script>
+```
+
+## Type Declarations
+
+```ts
+export type DateLike = Date | number | string | undefined
+export interface UseDateFormatOptions {
+  /**
+   * The locale(s) to used for dd/ddd/dddd/MMM/MMMM format
+   *
+   * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+   */
+  locales?: MaybeRefOrGetter<Intl.LocalesArgument>
+  /**
+   * A custom function to re-modify the way to display meridiem
+   *
+   */
+  customMeridiem?: (
+    hours: number,
+    minutes: number,
+    isLowercase?: boolean,
+    hasPeriod?: boolean,
+  ) => string
+}
+export declare function formatDate(
+  date: Date,
+  formatStr: string,
+  options?: UseDateFormatOptions,
+): string
+export declare function normalizeDate(date: DateLike): Date
+export type UseDateFormatReturn = ComputedRef<string>
+/**
+ * Get the formatted date according to the string of tokens passed in.
+ *
+ * @see https://vueuse.org/useDateFormat
+ * @param date - The date to format, can either be a `Date` object, a timestamp, or a string
+ * @param formatStr - The combination of tokens to format the date
+ * @param options - UseDateFormatOptions
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useDateFormat(
+  date: MaybeRefOrGetter<DateLike>,
+  formatStr?: MaybeRefOrGetter<string>,
+  options?: UseDateFormatOptions,
+): UseDateFormatReturn
+```

package/templates/skills/vueuse-functions/references/useDebounceFn.md

@@ -0,0 +1,100 @@
+---
+category: Utilities
+related: useThrottleFn
+---
+
+# useDebounceFn
+
+Debounce execution of a function.
+
+> Debounce is an overloaded waiter: if you keep asking, your requests will be ignored until you stop and give them some time to think about your latest inquiry.
+
+## Usage
+
+```ts
+import { useDebounceFn, useEventListener } from '@vueuse/core'
+
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000)
+
+useEventListener(window, 'resize', debouncedFn)
+```
+
+You can also pass a 3rd parameter to this, with a maximum wait time, similar to [lodash debounce](https://lodash.com/docs/4.17.15#debounce)
+
+```ts
+import { useDebounceFn, useEventListener } from '@vueuse/core'
+
+// If no invokation after 5000ms due to repeated input,
+// the function will be called anyway.
+const debouncedFn = useDebounceFn(() => {
+  // do something
+}, 1000, { maxWait: 5000 })
+
+useEventListener(window, 'resize', debouncedFn)
+```
+
+Optionally, you can get the return value of the function using promise operations.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedRequest = useDebounceFn(() => 'response', 1000)
+
+debouncedRequest().then((value) => {
+  console.log(value) // 'response'
+})
+
+// or use async/await
+async function doRequest() {
+  const value = await debouncedRequest()
+  console.log(value) // 'response'
+}
+```
+
+Since unhandled rejection error is quite annoying when developer doesn't need the return value, the promise will **NOT** be rejected if the function is canceled **by default**. You need to specify the option `rejectOnCancel: true` to capture the rejection.
+
+```ts
+import { useDebounceFn } from '@vueuse/core'
+
+const debouncedRequest = useDebounceFn(() => 'response', 1000, { rejectOnCancel: true })
+
+debouncedRequest()
+  .then((value) => {
+    // do something
+  })
+  .catch(() => {
+    // do something when canceled
+  })
+
+// calling it again will cancel the previous request and gets rejected
+setTimeout(debouncedRequest, 500)
+```
+
+## Recommended Reading
+
+- [**Debounce vs Throttle**: Definitive Visual Guide](https://kettanaito.com/blog/debounce-vs-throttle)
+
+## Type Declarations
+
+```ts
+export type UseDebounceFnReturn<T extends FunctionArgs> = PromisifyFn<T>
+/**
+ * Debounce execution of a function.
+ *
+ * @see https://vueuse.org/useDebounceFn
+ * @param  fn          A function to be executed after delay milliseconds debounced.
+ * @param  ms          A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
+ * @param  options     Options
+ *
+ * @return A new, debounce, function.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useDebounceFn<T extends FunctionArgs>(
+  fn: T,
+  ms?: MaybeRefOrGetter<number>,
+  options?: DebounceFilterOptions,
+): UseDebounceFnReturn<T>
+```

package/templates/skills/vueuse-functions/references/useDebouncedRefHistory.md

@@ -0,0 +1,40 @@
+---
+category: State
+related:
+  - useRefHistory
+  - useThrottledRefHistory
+---
+
+# useDebouncedRefHistory
+
+Shorthand for `useRefHistory` with debounced filter.
+
+## Usage
+
+This function takes a snapshot of your counter after 1000ms when the value of it starts to change.
+
+```ts
+import { useDebouncedRefHistory } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const counter = shallowRef(0)
+const { history, undo, redo } = useDebouncedRefHistory(counter, { deep: true, debounce: 1000 })
+```
+
+## Type Declarations
+
+```ts
+/**
+ * Shorthand for [useRefHistory](https://vueuse.org/useRefHistory) with debounce filter.
+ *
+ * @see https://vueuse.org/useDebouncedRefHistory
+ * @param source
+ * @param options
+ */
+export declare function useDebouncedRefHistory<Raw, Serialized = Raw>(
+  source: Ref<Raw>,
+  options?: Omit<UseRefHistoryOptions<Raw, Serialized>, "eventFilter"> & {
+    debounce?: MaybeRefOrGetter<number>
+  },
+): UseRefHistoryReturn<Raw, Serialized>
+```