aico-cli 2.1.7 → 2.1.23

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

@@ -0,0 +1,184 @@
+---
+category: Browser
+---
+
+# useEventListener
+
+Use EventListener with ease. Register using [addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) on mounted, and [removeEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener) automatically on unmounted.
+
+## Usage
+
+```ts
+import { useEventListener } from '@vueuse/core'
+
+useEventListener(document, 'visibilitychange', (evt) => {
+  console.log(evt)
+})
+```
+
+You can also pass a ref as the event target, `useEventListener` will unregister the previous event and register the new one when you change the target.
+
+```vue
+<script setup lang="ts">
+import { useEventListener } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const element = useTemplateRef('element')
+useEventListener(element, 'keydown', (e) => {
+  console.log(e.key)
+})
+</script>
+
+<template>
+  <div v-if="cond" ref="element">
+    Div1
+  </div>
+  <div v-else ref="element">
+    Div2
+  </div>
+</template>
+```
+
+You can also call the returned to unregister the listener.
+
+```ts
+import { useEventListener } from '@vueuse/core'
+
+const cleanup = useEventListener(document, 'keydown', (e) => {
+  console.log(e.key)
+})
+
+cleanup() // This will unregister the listener.
+```
+
+Note if your components also run in SSR (Server Side Rendering), you might get errors (like `document is not defined`) because DOM APIs like `document` and `window` are not available in Node.js. To avoid that you can put the logic inside `onMounted` hook.
+
+```ts
+import { useEventListener } from '@vueuse/core'
+// ---cut---
+// onMounted will only be called in the client side
+// so it guarantees the DOM APIs are available.
+onMounted(() => {
+  useEventListener(document, 'keydown', (e) => {
+    console.log(e.key)
+  })
+})
+```
+
+## Type Declarations
+
+```ts
+interface InferEventTarget<Events> {
+  addEventListener: (event: Events, fn?: any, options?: any) => any
+  removeEventListener: (event: Events, fn?: any, options?: any) => any
+}
+export type WindowEventName = keyof WindowEventMap
+export type DocumentEventName = keyof DocumentEventMap
+export type ShadowRootEventName = keyof ShadowRootEventMap
+export interface GeneralEventListener<E = Event> {
+  (evt: E): void
+}
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 1: Omitted Window target
+ *
+ * @see https://vueuse.org/useEventListener
+ */
+export declare function useEventListener<E extends keyof WindowEventMap>(
+  event: MaybeRefOrGetter<Arrayable<E>>,
+  listener: MaybeRef<Arrayable<(this: Window, ev: WindowEventMap[E]) => any>>,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 2: Explicitly Window target
+ *
+ * @see https://vueuse.org/useEventListener
+ * @param target
+ * @param event
+ * @param listener
+ * @param options
+ */
+export declare function useEventListener<E extends keyof WindowEventMap>(
+  target: Window,
+  event: MaybeRefOrGetter<Arrayable<E>>,
+  listener: MaybeRef<Arrayable<(this: Window, ev: WindowEventMap[E]) => any>>,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 3: Explicitly Document target
+ *
+ * @see https://vueuse.org/useEventListener
+ */
+export declare function useEventListener<E extends keyof DocumentEventMap>(
+  target: Document,
+  event: MaybeRefOrGetter<Arrayable<E>>,
+  listener: MaybeRef<
+    Arrayable<(this: Document, ev: DocumentEventMap[E]) => any>
+  >,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 4: Explicitly ShadowRoot target
+ *
+ * @see https://vueuse.org/useEventListener
+ */
+export declare function useEventListener<E extends keyof ShadowRootEventMap>(
+  target: MaybeRefOrGetter<Arrayable<ShadowRoot> | null | undefined>,
+  event: MaybeRefOrGetter<Arrayable<E>>,
+  listener: MaybeRef<
+    Arrayable<(this: ShadowRoot, ev: ShadowRootEventMap[E]) => any>
+  >,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 5: Explicitly HTMLElement target
+ *
+ * @see https://vueuse.org/useEventListener
+ */
+export declare function useEventListener<E extends keyof HTMLElementEventMap>(
+  target: MaybeRefOrGetter<Arrayable<HTMLElement> | null | undefined>,
+  event: MaybeRefOrGetter<Arrayable<E>>,
+  listener: MaybeRef<(this: HTMLElement, ev: HTMLElementEventMap[E]) => any>,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 6: Custom event target with event type infer
+ *
+ * @see https://vueuse.org/useEventListener
+ */
+export declare function useEventListener<
+  Names extends string,
+  EventType = Event,
+>(
+  target: MaybeRefOrGetter<
+    Arrayable<InferEventTarget<Names>> | null | undefined
+  >,
+  event: MaybeRefOrGetter<Arrayable<Names>>,
+  listener: MaybeRef<Arrayable<GeneralEventListener<EventType>>>,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 7: Custom event target fallback
+ *
+ * @see https://vueuse.org/useEventListener
+ */
+export declare function useEventListener<EventType = Event>(
+  target: MaybeRefOrGetter<Arrayable<EventTarget> | null | undefined>,
+  event: MaybeRefOrGetter<Arrayable<string>>,
+  listener: MaybeRef<Arrayable<GeneralEventListener<EventType>>>,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
+): Fn
+```

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

@@ -0,0 +1,204 @@
+---
+category: Network
+---
+
+# useEventSource
+
+An [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or [Server-Sent-Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) instance opens a persistent connection to an HTTP server, which sends events in text/event-stream format.
+
+## Usage
+
+```ts
+import { useEventSource } from '@vueuse/core'
+
+const { status, data, error, close } = useEventSource('https://event-source-url')
+```
+
+See the [Type Declarations](#type-declarations) for more options.
+
+### Named Events
+
+You can define named events with the second parameter
+
+```ts
+import { useEventSource } from '@vueuse/core'
+// ---cut---
+const { event, data } = useEventSource(
+  'https://event-source-url',
+  ['notice', 'update']
+)
+```
+
+### immediate
+
+Enable by default.
+
+Establish the connection immediately when the composable is called.
+
+### autoConnect
+
+Enable by default.
+
+If url is provided as a ref, when the url changes, it will automatically reconnect to the new url.
+
+### Auto Reconnection on Errors
+
+Reconnect on errors automatically (disabled by default).
+
+```ts
+import { useEventSource } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useEventSource(
+  'https://event-source-url',
+  [],
+  {
+    autoReconnect: true,
+  }
+)
+```
+
+Or with more controls over its behavior:
+
+```ts
+import { useEventSource } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useEventSource(
+  'https://event-source-url',
+  [],
+  {
+    autoReconnect: {
+      retries: 3,
+      delay: 1000,
+      onFailed() {
+        alert('Failed to connect EventSource after 3 retries')
+      },
+    },
+  }
+)
+```
+
+### Data Serialization
+
+Apply custom transformations to incoming data using a serialization function.
+
+```ts
+import { useEventSource } from '@vueuse/core'
+// ---cut---
+const { data } = useEventSource(
+  'https://event-source-url',
+  [],
+  {
+    serializer: {
+      read: rawData => JSON.parse(rawData),
+    },
+  }
+)
+
+// If server sends: '{"name":"John","age":30}'
+// data.value will be: { name: 'John', age: 30 }
+```
+
+## Type Declarations
+
+```ts
+export type EventSourceStatus = "CONNECTING" | "OPEN" | "CLOSED"
+export interface UseEventSourceOptions<Data> extends EventSourceInit {
+  /**
+   * Enabled auto reconnect
+   *
+   * @default false
+   */
+  autoReconnect?:
+    | boolean
+    | {
+        /**
+         * Maximum retry times.
+         *
+         * Or you can pass a predicate function (which returns true if you want to retry).
+         *
+         * @default -1
+         */
+        retries?: number | (() => boolean)
+        /**
+         * Delay for reconnect, in milliseconds
+         *
+         * @default 1000
+         */
+        delay?: number
+        /**
+         * On maximum retry times reached.
+         */
+        onFailed?: Fn
+      }
+  /**
+   * Immediately open the connection when calling this composable
+   *
+   * @default true
+   */
+  immediate?: boolean
+  /**
+   * Automatically connect to the websocket when URL changes
+   *
+   * @default true
+   */
+  autoConnect?: boolean
+  /**
+   * Custom data serialization
+   */
+  serializer?: {
+    read: (v?: string) => Data
+  }
+}
+export interface UseEventSourceReturn<Events extends string[], Data = any> {
+  /**
+   * Reference to the latest data received via the EventSource,
+   * can be watched to respond to incoming messages
+   */
+  data: ShallowRef<Data | null>
+  /**
+   * The current state of the connection, can be only one of:
+   * 'CONNECTING', 'OPEN' 'CLOSED'
+   */
+  status: ShallowRef<EventSourceStatus>
+  /**
+   * The latest named event
+   */
+  event: ShallowRef<Events[number] | null>
+  /**
+   * The current error
+   */
+  error: ShallowRef<Event | null>
+  /**
+   * Closes the EventSource connection gracefully.
+   */
+  close: EventSource["close"]
+  /**
+   * Reopen the EventSource connection.
+   * If there the current one is active, will close it before opening a new one.
+   */
+  open: Fn
+  /**
+   * Reference to the current EventSource instance.
+   */
+  eventSource: Ref<EventSource | null>
+  /**
+   * The last event ID string, for server-sent events.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/lastEventId
+   */
+  lastEventId: ShallowRef<string | null>
+}
+/**
+ * Reactive wrapper for EventSource.
+ *
+ * @see https://vueuse.org/useEventSource
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource EventSource
+ * @param url
+ * @param events
+ * @param options
+ */
+export declare function useEventSource<Events extends string[], Data = any>(
+  url: MaybeRefOrGetter<string | URL | undefined>,
+  events?: Events,
+  options?: UseEventSourceOptions<Data>,
+): UseEventSourceReturn<Events, Data>
+```

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

@@ -0,0 +1,185 @@
+---
+category: '@RxJS'
+---
+
+# useExtractedObservable
+
+Use an RxJS [`Observable`](https://rxjs.dev/guide/observable) as extracted from one or more composables, return a `ref`,
+and automatically unsubscribe from it when the component is unmounted.
+
+Automatically unsubscribe on observable change, and automatically unsubscribe from it when the component is unmounted.
+
+Supports signatures that match all overloads
+of [`watch`](https://vuejs.org/guide/essentials/watchers.html#basic-example).
+
+## Usage
+
+<!-- TODO: import rxjs error if enable twoslash -->
+
+```ts no-twoslash
+import { useExtractedObservable } from '@vueuse/rxjs'
+import ObservableSocket from 'observable-socket'
+import { computed } from 'vue'
+import { makeSocket, useUser } from '../some/lib/func'
+
+// setup()
+const user = useUser()
+const lastMessage = useExtractedObservable(user, u => ObservableSocket.create(makeSocket(u.id)).down)
+```
+
+If you want to add custom error handling to an `Observable` 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 { useExtractedObservable } from '@vueuse/rxjs'
+import { interval } from 'rxjs'
+import { mapTo, scan, startWith, tap } from 'rxjs/operators'
+import { shallowRef } from 'vue'
+
+// setup()
+const start = shallowRef(0)
+
+const count = useExtractedObservable(
+  start,
+  (start) => {
+    return interval(1000).pipe(
+      mapTo(1),
+      startWith(start),
+      scan((total, next) => next + total),
+      tap((n) => {
+        if (n === 10)
+          throw new Error('oops')
+      })
+    )
+  },
+  {
+    onError: (err) => {
+      console.log(err.message) // "oops"
+    },
+  }
+)
+```
+
+You can also supply an optional `onComplete` configuration if you need to attach special behavior when the watched
+observable completes.
+
+```ts no-twoslash
+import { useExtractedObservable } from '@vueuse/rxjs'
+import { interval } from 'rxjs'
+import { mapTo, scan, startWith, takeWhile } from 'rxjs/operators'
+import { shallowRef } from 'vue'
+
+// setup()
+const start = shallowRef(0)
+
+const count = useExtractedObservable(
+  start,
+  (start) => {
+    return interval(1000).pipe(
+      mapTo(1),
+      startWith(start),
+      scan((total, next) => next + total),
+      takeWhile(num => num < 10)
+    )
+  },
+  {
+    onComplete: () => {
+      console.log('Done!')
+    },
+  }
+)
+```
+
+If you want, you can also pass `watch` options as the last argument:
+
+```ts no-twoslash
+import { useExtractedObservable } from '@vueuse/rxjs'
+import { interval } from 'rxjs'
+import { mapTo, scan, startWith, takeWhile } from 'rxjs/operators'
+import { shallowRef } from 'vue'
+
+// setup()
+const start = shallowRef<number>()
+
+const count = useExtractedObservable(
+  start,
+  (start) => {
+    return interval(1000).pipe(
+      mapTo(1),
+      startWith(start),
+      scan((total, next) => next + total),
+      takeWhile(num => num < 10)
+    )
+  },
+  {},
+  {
+    immediate: false
+  }
+)
+```
+
+## Type Declarations
+
+```ts
+export interface UseExtractedObservableOptions<E>
+  extends UseObservableOptions<E> {
+  onComplete?: () => void
+}
+export declare function useExtractedObservable<
+  T extends MultiWatchSources,
+  E,
+  Immediate extends Readonly<boolean> = false,
+>(
+  sources: [...T],
+  extractor: WatchExtractedObservableCallback<
+    MapSources<T>,
+    MapOldSources<T, Immediate>,
+    E
+  >,
+  options?: UseExtractedObservableOptions<E>,
+  watchOptions?: WatchOptions<Immediate>,
+): Readonly<ShallowRef<E>>
+export declare function useExtractedObservable<
+  T extends Readonly<MultiWatchSources>,
+  E,
+  Immediate extends Readonly<boolean> = false,
+>(
+  sources: T,
+  extractor: WatchExtractedObservableCallback<
+    MapSources<T>,
+    MapOldSources<T, Immediate>,
+    E
+  >,
+  options?: UseExtractedObservableOptions<E>,
+  watchOptions?: WatchOptions<Immediate>,
+): Readonly<ShallowRef<E>>
+export declare function useExtractedObservable<
+  T,
+  E,
+  Immediate extends Readonly<boolean> = false,
+>(
+  sources: WatchSource<T>,
+  extractor: WatchExtractedObservableCallback<
+    T,
+    Immediate extends true ? T | undefined : T,
+    E
+  >,
+  options?: UseExtractedObservableOptions<E>,
+  watchOptions?: WatchOptions<Immediate>,
+): Readonly<ShallowRef<E>>
+export declare function useExtractedObservable<
+  T extends object,
+  E,
+  Immediate extends Readonly<boolean> = false,
+>(
+  sources: T,
+  extractor: WatchExtractedObservableCallback<
+    T,
+    Immediate extends true ? T | undefined : T,
+    E
+  >,
+  options?: UseExtractedObservableOptions<E>,
+  watchOptions?: WatchOptions<Immediate>,
+): Readonly<ShallowRef<E>>
+```

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

@@ -0,0 +1,71 @@
+---
+category: Browser
+---
+
+# useEyeDropper
+
+Reactive [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API)
+
+## Usage
+
+```ts
+import { useEyeDropper } from '@vueuse/core'
+
+const { isSupported, open, sRGBHex } = useEyeDropper()
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseEyeDropper v-slot="{ isSupported, sRGBHex, open }">
+    <button :disabled="!isSupported" @click="() => open()">
+      sRGBHex: {{ sRGBHex }}
+    </button>
+  </UseEyeDropper>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface EyeDropperOpenOptions {
+  /**
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+   */
+  signal?: AbortSignal
+}
+export interface EyeDropper {
+  new (): EyeDropper
+  open: (options?: EyeDropperOpenOptions) => Promise<{
+    sRGBHex: string
+  }>
+  [Symbol.toStringTag]: "EyeDropper"
+}
+export interface UseEyeDropperOptions {
+  /**
+   * Initial sRGBHex.
+   *
+   * @default ''
+   */
+  initialValue?: string
+}
+/**
+ * Reactive [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API)
+ *
+ * @see https://vueuse.org/useEyeDropper
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useEyeDropper(options?: UseEyeDropperOptions): {
+  isSupported: ComputedRef<boolean>
+  sRGBHex: ShallowRef<string, string>
+  open: (openOptions?: EyeDropperOpenOptions) => Promise<
+    | {
+        sRGBHex: string
+      }
+    | undefined
+  >
+}
+export type UseEyeDropperReturn = ReturnType<typeof useEyeDropper>
+```

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

@@ -0,0 +1,67 @@
+---
+category: Browser
+---
+
+# useFavicon
+
+Reactive favicon
+
+## Usage
+
+```ts {3}
+import { useFavicon } from '@vueuse/core'
+
+const icon = useFavicon()
+
+icon.value = 'dark.png' // change current icon
+```
+
+### Passing a source ref
+
+You can pass a `ref` to it, changes from of the source ref will be reflected to your favicon automatically.
+
+```ts {7}
+import { useFavicon, usePreferredDark } from '@vueuse/core'
+import { computed } from 'vue'
+
+const isDark = usePreferredDark()
+const favicon = computed(() => isDark.value ? 'dark.png' : 'light.png')
+
+useFavicon(favicon)
+```
+
+When a source ref is passed, the return ref will be identical to the source ref
+
+```ts
+import { useFavicon } from '@vueuse/core'
+// ---cut---
+const source = shallowRef('icon.png')
+const icon = useFavicon(source)
+
+console.log(icon === source) // true
+```
+
+## Type Declarations
+
+```ts
+export interface UseFaviconOptions extends ConfigurableDocument {
+  baseUrl?: string
+  rel?: string
+}
+/**
+ * Reactive favicon.
+ *
+ * @see https://vueuse.org/useFavicon
+ * @param newIcon
+ * @param options
+ */
+export declare function useFavicon(
+  newIcon: ReadonlyRefOrGetter<string | null | undefined>,
+  options?: UseFaviconOptions,
+): ComputedRef<string | null | undefined>
+export declare function useFavicon(
+  newIcon?: MaybeRef<string | null | undefined>,
+  options?: UseFaviconOptions,
+): Ref<string | null | undefined>
+export type UseFaviconReturn = ReturnType<typeof useFavicon>
+```