ads-fe 0.0.1

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

@@ -0,0 +1,182 @@
+---
+category: Component
+---
+
+# useVirtualList
+
+::: warning
+Consider using [`@tanstack/vue-virtual`](https://tanstack.com/virtual/v3/docs/framework/vue/vue-virtual) instead, if you are looking for more features.
+:::
+
+Create virtual lists with ease. Virtual lists (sometimes called [_virtual scrollers_](https://vue-virtual-scroller-demo.netlify.app/)) allow you to render a large number of items performantly. They only render the minimum number of DOM nodes necessary to show the items within the `container` element by using the `wrapper` element to emulate the container element's full height.
+
+## Usage
+
+### Simple list
+
+```ts
+import { useVirtualList } from '@vueuse/core'
+
+const { list, containerProps, wrapperProps } = useVirtualList(
+  Array.from(Array.from({ length: 99999 }).keys()),
+  {
+    // Keep `itemHeight` in sync with the item's row.
+    itemHeight: 22,
+  },
+)
+```
+
+### Config
+
+| State      | Type     | Description                                                                                     |
+| ---------- | -------- | ----------------------------------------------------------------------------------------------- |
+| itemHeight | `number` | ensure that the total height of the `wrapper` element is calculated correctly.\*                |
+| itemWidth  | `number` | ensure that the total width of the `wrapper` element is calculated correctly.\*                 |
+| overscan   | `number` | number of pre-rendered DOM nodes. Prevents whitespace between items if you scroll very quickly. |
+
+\* The `itemHeight` or `itemWidth` must be kept in sync with the height of each row rendered. If you are seeing extra whitespace or jitter when scrolling to the bottom of the list, ensure the `itemHeight` or `itemWidth` is the same height as the row.
+
+### Reactive list
+
+```ts
+import { useToggle, useVirtualList } from '@vueuse/core'
+import { computed } from 'vue'
+
+const [isEven, toggle] = useToggle()
+const allItems = Array.from(Array.from({ length: 99999 }).keys())
+const filteredList = computed(() => allItems.filter(i => isEven.value ? i % 2 === 0 : i % 2 === 1))
+
+const { list, containerProps, wrapperProps } = useVirtualList(
+  filteredList,
+  {
+    itemHeight: 22,
+  },
+)
+```
+
+```vue
+<template>
+  <p>Showing {{ isEven ? 'even' : 'odd' }} items</p>
+  <button @click="toggle">
+    Toggle Even/Odd
+  </button>
+  <div v-bind="containerProps" style="height: 300px">
+    <div v-bind="wrapperProps">
+      <div v-for="item in list" :key="item.index" style="height: 22px">
+        Row: {{ item.data }}
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+### Horizontal list
+
+```ts
+import { useVirtualList } from '@vueuse/core'
+
+const allItems = Array.from(Array.from({ length: 99999 }).keys())
+
+const { list, containerProps, wrapperProps } = useVirtualList(
+  allItems,
+  {
+    itemWidth: 200,
+  },
+)
+```
+
+```vue
+<template>
+  <div v-bind="containerProps" style="height: 300px">
+    <div v-bind="wrapperProps">
+      <div v-for="item in list" :key="item.index" style="width: 200px">
+        Row: {{ item.data }}
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseVirtualList :list="list" :options="options" height="300px">
+    <template #default="props">
+      <!-- you can get current item of list here -->
+      <div style="height: 22px">
+        Row {{ props.index }} {{ props.data }}
+      </div>
+    </template>
+  </UseVirtualList>
+</template>
+```
+
+To scroll to a specific element, the component exposes `scrollTo(index: number) => void`.
+
+## Type Declarations
+
+```ts
+type UseVirtualListItemSize = number | ((index: number) => number)
+export interface UseHorizontalVirtualListOptions extends UseVirtualListOptionsBase {
+  /**
+   * item width, accept a pixel value or a function that returns the width
+   *
+   * @default 0
+   */
+  itemWidth: UseVirtualListItemSize
+}
+export interface UseVerticalVirtualListOptions extends UseVirtualListOptionsBase {
+  /**
+   * item height, accept a pixel value or a function that returns the height
+   *
+   * @default 0
+   */
+  itemHeight: UseVirtualListItemSize
+}
+export interface UseVirtualListOptionsBase {
+  /**
+   * the extra buffer items outside of the view area
+   *
+   * @default 5
+   */
+  overscan?: number
+}
+export type UseVirtualListOptions =
+  | UseHorizontalVirtualListOptions
+  | UseVerticalVirtualListOptions
+export interface UseVirtualListItem<T> {
+  data: T
+  index: number
+}
+export interface UseVirtualListReturn<T> {
+  list: Ref<UseVirtualListItem<T>[]>
+  scrollTo: (index: number) => void
+  containerProps: {
+    ref: Ref<HTMLElement | null>
+    onScroll: () => void
+    style: StyleValue
+  }
+  wrapperProps: ComputedRef<{
+    style:
+      | {
+          width: string
+          height: string
+          marginTop: string
+        }
+      | {
+          width: string
+          height: string
+          marginLeft: string
+          display: string
+        }
+  }>
+}
+/**
+ * Please consider using [`vue-virtual-scroller`](https://github.com/Akryum/vue-virtual-scroller) if you are looking for more features.
+ */
+export declare function useVirtualList<T = any>(
+  list: MaybeRef<readonly T[]>,
+  options: UseVirtualListOptions,
+): UseVirtualListReturn<T>
+```

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

@@ -0,0 +1,51 @@
+---
+category: Browser
+---
+
+# useWakeLock
+
+Reactive [Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API). Provides a way to prevent devices from dimming or locking the screen when an application needs to keep running.
+
+## Usage
+
+```ts
+import { useWakeLock } from '@vueuse/core'
+
+const { isSupported, isActive, forceRequest, request, release } = useWakeLock()
+```
+
+When `request` is called, the wake lock will be requested if the document is visible. Otherwise, the request will be queued until the document becomes visible. If the request is successful, `isActive` will be **true**. Whenever the document is hidden, the `isActive` will be **false**.
+
+When `release` is called, the wake lock will be released. If there is a queued request, it will be canceled.
+
+To request a wake lock immediately, even if the document is hidden, use `forceRequest`. Note that this may throw an error if the document is hidden.
+
+## Type Declarations
+
+```ts
+type WakeLockType = "screen"
+export interface WakeLockSentinel extends EventTarget {
+  type: WakeLockType
+  released: boolean
+  release: () => Promise<void>
+}
+export type UseWakeLockOptions = ConfigurableNavigator & ConfigurableDocument
+export interface UseWakeLockReturn extends Supportable {
+  sentinel: ShallowRef<WakeLockSentinel | null>
+  isActive: ComputedRef<boolean>
+  request: (type: WakeLockType) => Promise<void>
+  forceRequest: (type: WakeLockType) => Promise<void>
+  release: () => Promise<void>
+}
+/**
+ * Reactive Screen Wake Lock API.
+ *
+ * @see https://vueuse.org/useWakeLock
+ * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useWakeLock(
+  options?: UseWakeLockOptions,
+): UseWakeLockReturn
+```

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

@@ -0,0 +1,175 @@
+---
+category: Browser
+---
+
+# useWebNotification
+
+Reactive [Notification](https://developer.mozilla.org/en-US/docs/Web/API/notification)
+
+The Web Notification interface of the Notifications API is used to configure and display desktop notifications to the user.
+
+## Usage
+
+::: tip
+Before an app can send a notification, the user must grant the application the right to do so. The user's OS settings may also prevent expected notification behaviour.
+:::
+
+```ts
+import { useWebNotification } from '@vueuse/core'
+
+const {
+  isSupported,
+  notification,
+  permissionGranted,
+  show,
+  close,
+  onClick,
+  onShow,
+  onError,
+  onClose,
+} = useWebNotification({
+  title: 'Hello, VueUse world!',
+  dir: 'auto',
+  lang: 'en',
+  renotify: true,
+  tag: 'test',
+})
+
+if (isSupported.value && permissionGranted.value)
+  show()
+```
+
+This composable also utilizes the createEventHook utility from '@vueuse/shared`:
+
+```ts
+import { useWebNotification } from '@vueuse/core'
+
+const { onClick, onShow, onError, onClose, } = useWebNotification()
+// ---cut---
+onClick((evt: Event) => {
+  // Do something with the notification on:click event...
+})
+
+onShow((evt: Event) => {
+  // Do something with the notification on:show event...
+})
+
+onError((evt: Event) => {
+  // Do something with the notification on:error event...
+})
+
+onClose((evt: Event) => {
+  // Do something with the notification on:close event...
+})
+```
+
+## Type Declarations
+
+```ts
+export interface WebNotificationOptions {
+  /**
+   * The title read-only property of the Notification interface indicates
+   * the title of the notification
+   *
+   * @default ''
+   */
+  title?: string
+  /**
+   * The body string of the notification as specified in the constructor's
+   * options parameter.
+   *
+   * @default ''
+   */
+  body?: string
+  /**
+   * The text direction of the notification as specified in the constructor's
+   * options parameter.
+   *
+   * @default ''
+   */
+  dir?: "auto" | "ltr" | "rtl"
+  /**
+   * The language code of the notification as specified in the constructor's
+   * options parameter.
+   *
+   * @default DOMString
+   */
+  lang?: string
+  /**
+   * The ID of the notification(if any) as specified in the constructor's options
+   * parameter.
+   *
+   * @default ''
+   */
+  tag?: string
+  /**
+   * The URL of the image used as an icon of the notification as specified
+   * in the constructor's options parameter.
+   *
+   * @default ''
+   */
+  icon?: string
+  /**
+   * Specifies whether the user should be notified after a new notification
+   * replaces an old one.
+   *
+   * @default false
+   */
+  renotify?: boolean
+  /**
+   * A boolean value indicating that a notification should remain active until the
+   * user clicks or dismisses it, rather than closing automatically.
+   *
+   * @default false
+   */
+  requireInteraction?: boolean
+  /**
+   * The silent read-only property of the Notification interface specifies
+   * whether the notification should be silent, i.e., no sounds or vibrations
+   * should be issued, regardless of the device settings.
+   *
+   * @default false
+   */
+  silent?: boolean
+  /**
+   * Specifies a vibration pattern for devices with vibration hardware to emit.
+   * A vibration pattern, as specified in the Vibration API spec
+   *
+   * @see https://w3c.github.io/vibration/
+   */
+  vibrate?: number[]
+}
+export interface UseWebNotificationOptions
+  extends ConfigurableWindow, WebNotificationOptions {
+  /**
+   * Request for permissions onMounted if it's not granted.
+   *
+   * Can be disabled and calling `ensurePermissions` to grant afterwords.
+   *
+   * @default true
+   */
+  requestPermissions?: boolean
+}
+export interface UseWebNotificationReturn extends Supportable {
+  notification: ShallowRef<Notification | null>
+  ensurePermissions: () => Promise<boolean | undefined>
+  permissionGranted: ShallowRef<boolean>
+  show: (
+    overrides?: WebNotificationOptions,
+  ) => Promise<Notification | undefined>
+  close: () => void
+  onClick: EventHookOn<Event>
+  onShow: EventHookOn<Event>
+  onError: EventHookOn<Event>
+  onClose: EventHookOn<Event>
+}
+/**
+ * Reactive useWebNotification
+ *
+ * @see https://vueuse.org/useWebNotification
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/notification
+ */
+export declare function useWebNotification(
+  options?: UseWebNotificationOptions,
+): UseWebNotificationReturn
+```

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

@@ -0,0 +1,299 @@
+---
+category: Network
+---
+
+# useWebSocket
+
+Reactive [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) client.
+
+## Usage
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+
+const { status, data, send, open, close, ws } = useWebSocket('ws://websocketurl')
+```
+
+### Return Values
+
+| Property | Type                                      | Description                          |
+| -------- | ----------------------------------------- | ------------------------------------ |
+| `data`   | `Ref<any>`                                | Latest received data                 |
+| `status` | `Ref<'OPEN' \| 'CONNECTING' \| 'CLOSED'>` | Connection status                    |
+| `ws`     | `Ref<WebSocket>`                          | WebSocket instance                   |
+| `send`   | `(data, useBuffer?) => boolean`           | Send data (buffers if not connected) |
+| `open`   | `() => void`                              | Open/reconnect the connection        |
+| `close`  | `(code?, reason?) => void`                | Close the connection                 |
+
+### Callbacks
+
+```ts
+const { data } = useWebSocket('ws://websocketurl', {
+  onConnected(ws) {
+    console.log('Connected!')
+  },
+  onDisconnected(ws, event) {
+    console.log('Disconnected!', event.code)
+  },
+  onError(ws, event) {
+    console.error('Error:', event)
+  },
+  onMessage(ws, event) {
+    console.log('Message:', event.data)
+  },
+})
+```
+
+See the [Type Declarations](#type-declarations) for more options.
+
+### immediate
+
+Enable by default.
+
+Establish the connection immediately when the composable is called.
+
+### autoConnect
+
+Enable by default.
+
+If a URL is provided as a ref, when the URL changes, it will automatically reconnect to the new URL.
+
+### autoClose
+
+Enable by default.
+
+This will call `close()` automatically when the `beforeunload` event is triggered or the associated effect scope is stopped.
+
+### autoReconnect
+
+Reconnect on errors automatically (disabled by default).
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useWebSocket('ws://websocketurl', {
+  autoReconnect: true,
+})
+```
+
+Or with more controls over its behavior:
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useWebSocket('ws://websocketurl', {
+  autoReconnect: {
+    retries: 3,
+    delay: 1000,
+    onFailed() {
+      alert('Failed to connect WebSocket after 3 retries')
+    },
+  },
+})
+```
+
+You can also pass a function to `delay` to calculate the delay based on the number of retries. This is useful for implementing exponential backoff:
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useWebSocket('ws://websocketurl', {
+  autoReconnect: {
+    retries: 5,
+    // Exponential backoff: 1s, 2s, 4s, 8s, 16s
+    delay: retries => Math.min(1000 * 2 ** (retries - 1), 30000),
+  },
+})
+```
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useWebSocket('ws://websocketurl', {
+  autoReconnect: {
+    retries: 5,
+    // Linear backoff: 1s, 2s, 3s, 4s, 5s
+    delay: retries => retries * 1000,
+  },
+})
+```
+
+Explicitly calling `close()` won't trigger the auto reconnection.
+
+### heartbeat
+
+It's common practice to send a small message (heartbeat) for every given time passed to keep the connection active. In this function we provide a convenient helper to do it:
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useWebSocket('ws://websocketurl', {
+  heartbeat: true,
+})
+```
+
+Or with more controls:
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, close } = useWebSocket('ws://websocketurl', {
+  heartbeat: {
+    message: 'ping',
+    scheduler: cb => useIntervalFn(cb, 2000),
+    pongTimeout: 1000,
+  },
+})
+```
+
+### Sub-protocols
+
+List of one or more subprotocols to use, in this case SOAP and WAMP.
+
+```ts
+import { useWebSocket } from '@vueuse/core'
+// ---cut---
+const { status, data, send, open, close } = useWebSocket('ws://websocketurl', {
+  protocols: ['soap'], // ['soap', 'wamp']
+})
+```
+
+## Type Declarations
+
+```ts
+export type WebSocketStatus = "OPEN" | "CONNECTING" | "CLOSED"
+export type WebSocketHeartbeatMessage = string | ArrayBuffer | Blob
+export interface UseWebSocketOptions {
+  onConnected?: (ws: WebSocket) => void
+  onDisconnected?: (ws: WebSocket, event: CloseEvent) => void
+  onError?: (ws: WebSocket, event: Event) => void
+  onMessage?: (ws: WebSocket, event: MessageEvent) => void
+  /**
+   * Send heartbeat for every x milliseconds passed
+   *
+   * @default false
+   */
+  heartbeat?:
+    | boolean
+    | (ConfigurableScheduler & {
+        /**
+         * Message for the heartbeat
+         *
+         * @default 'ping'
+         */
+        message?: MaybeRefOrGetter<WebSocketHeartbeatMessage>
+        /**
+         * Response message for the heartbeat, if undefined the message will be used
+         */
+        responseMessage?: MaybeRefOrGetter<WebSocketHeartbeatMessage>
+        /**
+         * Interval, in milliseconds
+         *
+         * @deprecated Please use `scheduler` option instead
+         * @default 1000
+         */
+        interval?: number
+        /**
+         * Heartbeat response timeout, in milliseconds
+         *
+         * @default 1000
+         */
+        pongTimeout?: number
+      })
+  /**
+   * 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 | ((retried: number) => boolean)
+        /**
+         * Delay for reconnect, in milliseconds
+         *
+         * Or you can pass a function to calculate the delay based on the number of retries.
+         *
+         * @default 1000
+         */
+        delay?: number | ((retries: number) => 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
+  /**
+   * Automatically close a connection
+   *
+   * @default true
+   */
+  autoClose?: boolean
+  /**
+   * List of one or more sub-protocol strings
+   *
+   * @default []
+   */
+  protocols?: string[]
+}
+export interface UseWebSocketReturn<T> {
+  /**
+   * Reference to the latest data received via the websocket,
+   * can be watched to respond to incoming messages
+   */
+  data: ShallowRef<T | null>
+  /**
+   * The current websocket status, can be only one of:
+   * 'OPEN', 'CONNECTING', 'CLOSED'
+   */
+  status: ShallowRef<WebSocketStatus>
+  /**
+   * Closes the websocket connection gracefully.
+   */
+  close: WebSocket["close"]
+  /**
+   * Reopen the websocket connection.
+   * If there the current one is active, will close it before opening a new one.
+   */
+  open: Fn
+  /**
+   * Sends data through the websocket connection.
+   *
+   * @param data
+   * @param useBuffer when the socket is not yet open, store the data into the buffer and sent them one connected. Default to true.
+   */
+  send: (data: string | ArrayBuffer | Blob, useBuffer?: boolean) => boolean
+  /**
+   * Reference to the WebSocket instance.
+   */
+  ws: ShallowRef<WebSocket | undefined>
+}
+/**
+ * Reactive WebSocket client.
+ *
+ * @see https://vueuse.org/useWebSocket
+ * @param url
+ */
+export declare function useWebSocket<Data = any>(
+  url: MaybeRefOrGetter<string | URL | undefined>,
+  options?: UseWebSocketOptions,
+): UseWebSocketReturn<Data>
+```