aico-cli 2.1.1 → 2.1.23

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

@@ -0,0 +1,83 @@
+---
+category: Elements
+---
+
+# useDropZone
+
+Create a zone where files can be dropped.
+
+::: warning
+
+Due to Safari browser limitations, file type validation is only possible during the drop event, not during drag events. As a result, the `isOverDropZone` value will always be `true` during drag operations in Safari, regardless of file type.
+
+:::
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useDropZone } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const dropZoneRef = useTemplateRef('dropZoneRef')
+
+function onDrop(files: File[] | null) {
+  // called when files are dropped on zone
+}
+
+const { isOverDropZone } = useDropZone(dropZoneRef, {
+  onDrop,
+  // specify the types of data to be received.
+  dataTypes: ['image/jpeg'],
+  // control multi-file drop
+  multiple: true,
+  // whether to prevent default behavior for unhandled events
+  preventDefaultForUnhandled: false,
+})
+</script>
+
+<template>
+  <div ref="dropZoneRef">
+    Drop files here
+  </div>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseDropZoneReturn {
+  files: ShallowRef<File[] | null>
+  isOverDropZone: ShallowRef<boolean>
+}
+export interface UseDropZoneOptions {
+  /**
+   * Allowed data types, if not set, all data types are allowed.
+   * Also can be a function to check the data types.
+   */
+  dataTypes?:
+    | MaybeRef<readonly string[]>
+    | ((types: readonly string[]) => boolean)
+  /**
+   * Similar to dataTypes, but exposes the DataTransferItemList for custom validation.
+   * If provided, this function takes precedence over dataTypes.
+   */
+  checkValidity?: (items: DataTransferItemList) => boolean
+  onDrop?: (files: File[] | null, event: DragEvent) => void
+  onEnter?: (files: File[] | null, event: DragEvent) => void
+  onLeave?: (files: File[] | null, event: DragEvent) => void
+  onOver?: (files: File[] | null, event: DragEvent) => void
+  /**
+   * Allow multiple files to be dropped. Defaults to true.
+   */
+  multiple?: boolean
+  /**
+   * Prevent default behavior for unhandled events. Defaults to false.
+   */
+  preventDefaultForUnhandled?: boolean
+}
+export declare function useDropZone(
+  target: MaybeRefOrGetter<HTMLElement | Document | null | undefined>,
+  options?: UseDropZoneOptions | UseDropZoneOptions["onDrop"],
+): UseDropZoneReturn
+```

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

@@ -0,0 +1,131 @@
+---
+category: Elements
+---
+
+# useElementBounding
+
+Reactive [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of an HTML element
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useElementBounding } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const { x, y, top, right, bottom, left, width, height } = useElementBounding(el)
+</script>
+
+<template>
+  <div ref="el" />
+</template>
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseElementBounding v-slot="{ width, height }">
+    Width: {{ width }} Height: {{ height }}
+  </UseElementBounding>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script setup lang="ts">
+import { vElementBounding } from '@vueuse/components'
+
+interface BoundingType {
+  height: number
+  bottom: number
+  left: number
+  right: number
+  top: number
+  width: number
+  x: number
+  y: number
+}
+
+function onBounding({ height, bottom, left, right, top, width, x, y }: BoundingType) {
+  console.log(height, bottom, left, right, top, width, x, y)
+}
+
+const options = {
+  reset: true,
+  windowResize: true,
+  windowScroll: true,
+  immediate: true,
+  updateTiming: 'sync',
+}
+</script>
+
+<template>
+  <textarea v-element-bounding="onBounding" />
+  <!-- with options -->
+  <textarea v-element-bounding="[onBounding, options]" />
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseElementBoundingOptions {
+  /**
+   * Reset values to 0 on component unmounted
+   *
+   * @default true
+   */
+  reset?: boolean
+  /**
+   * Listen to window resize event
+   *
+   * @default true
+   */
+  windowResize?: boolean
+  /**
+   * Listen to window scroll event
+   *
+   * @default true
+   */
+  windowScroll?: boolean
+  /**
+   * Immediately call update on component mounted
+   *
+   * @default true
+   */
+  immediate?: boolean
+  /**
+   * Timing to recalculate the bounding box
+   *
+   * Setting to `next-frame` can be useful when using this together with something like {@link useBreakpoints}
+   * and therefore the layout (which influences the bounding box of the observed element) is not updated on the current tick.
+   *
+   * @default 'sync'
+   */
+  updateTiming?: "sync" | "next-frame"
+}
+/**
+ * Reactive bounding box of an HTML element.
+ *
+ * @see https://vueuse.org/useElementBounding
+ * @param target
+ */
+export declare function useElementBounding(
+  target: MaybeComputedElementRef,
+  options?: UseElementBoundingOptions,
+): {
+  height: ShallowRef<number, number>
+  bottom: ShallowRef<number, number>
+  left: ShallowRef<number, number>
+  right: ShallowRef<number, number>
+  top: ShallowRef<number, number>
+  width: ShallowRef<number, number>
+  x: ShallowRef<number, number>
+  y: ShallowRef<number, number>
+  update: () => void
+}
+export type UseElementBoundingReturn = ReturnType<typeof useElementBounding>
+```

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

@@ -0,0 +1,45 @@
+---
+category: Sensors
+---
+
+# useElementByPoint
+
+Reactive element by point.
+
+## Usage
+
+```ts
+import { useElementByPoint, useMouse } from '@vueuse/core'
+
+const { x, y } = useMouse({ type: 'client' })
+const { element } = useElementByPoint({ x, y })
+```
+
+## Type Declarations
+
+```ts
+export interface UseElementByPointOptions<Multiple extends boolean = false>
+  extends ConfigurableDocument {
+  x: MaybeRefOrGetter<number>
+  y: MaybeRefOrGetter<number>
+  multiple?: MaybeRefOrGetter<Multiple>
+  immediate?: boolean
+  interval?: "requestAnimationFrame" | number
+}
+export interface UseElementByPointReturn<Multiple extends boolean = false>
+  extends Pausable {
+  isSupported: ComputedRef<boolean>
+  element: ShallowRef<
+    Multiple extends true ? HTMLElement[] : HTMLElement | null
+  >
+}
+/**
+ * Reactive element by point.
+ *
+ * @see https://vueuse.org/useElementByPoint
+ * @param options - UseElementByPointOptions
+ */
+export declare function useElementByPoint<M extends boolean = false>(
+  options: UseElementByPointOptions<M>,
+): UseElementByPointReturn<M>
+```

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

@@ -0,0 +1,79 @@
+---
+category: Sensors
+---
+
+# useElementHover
+
+Reactive element's hover state.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useElementHover } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const myHoverableElement = useTemplateRef('myHoverableElement')
+const isHovered = useElementHover(myHoverableElement)
+</script>
+
+<template>
+  <button ref="myHoverableElement">
+    {{ isHovered }}
+  </button>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script setup lang="ts">
+import { vElementHover } from '@vueuse/components'
+import { shallowRef } from 'vue'
+
+const isHovered = shallowRef(false)
+function onHover(state: boolean) {
+  isHovered.value = state
+}
+</script>
+
+<template>
+  <button v-element-hover="onHover">
+    {{ isHovered ? 'Thank you!' : 'Hover me' }}
+  </button>
+</template>
+```
+
+You can also provide hover options:
+
+```vue
+<script setup lang="ts">
+import { vElementHover } from '@vueuse/components'
+import { shallowRef } from 'vue'
+
+const isHovered = shallowRef(false)
+function onHover(hovered: boolean) {
+  isHovered.value = hovered
+}
+</script>
+
+<template>
+  <button v-element-hover="[onHover, { delayEnter: 1000 }]">
+    <span>{{ isHovered ? 'Thank you!' : 'Hover me' }}</span>
+  </button>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseElementHoverOptions extends ConfigurableWindow {
+  delayEnter?: number
+  delayLeave?: number
+  triggerOnRemoval?: boolean
+}
+export declare function useElementHover(
+  el: MaybeRefOrGetter<EventTarget | null | undefined>,
+  options?: UseElementHoverOptions,
+): ShallowRef<boolean>
+```

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

@@ -0,0 +1,78 @@
+---
+category: Elements
+---
+
+# useElementSize
+
+Reactive size of an HTML element. [ResizeObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useElementSize } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const { width, height } = useElementSize(el)
+</script>
+
+<template>
+  <div ref="el">
+    Height: {{ height }}
+    Width: {{ width }}
+  </div>
+</template>
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseElementSize v-slot="{ width, height }">
+    Width: {{ width }} Height: {{ height }}
+  </UseElementSize>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script setup lang="ts">
+import { vElementSize } from '@vueuse/components'
+
+function onResize({ width, height }: { width: number, height: number }) {
+  console.log(width, height)
+}
+</script>
+
+<template>
+  <textarea v-element-size="onResize" />
+  <!-- with options -->
+  <textarea v-element-size="[onResize, { width: 100, height: 100 }, { box: 'content-box' }]" />
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface ElementSize {
+  width: number
+  height: number
+}
+/**
+ * Reactive size of an HTML element.
+ *
+ * @see https://vueuse.org/useElementSize
+ */
+export declare function useElementSize(
+  target: MaybeComputedElementRef,
+  initialSize?: ElementSize,
+  options?: UseResizeObserverOptions,
+): {
+  width: ShallowRef<number, number>
+  height: ShallowRef<number, number>
+  stop: () => void
+}
+export type UseElementSizeReturn = ReturnType<typeof useElementSize>
+```

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

@@ -0,0 +1,126 @@
+---
+category: Elements
+---
+
+# useElementVisibility
+
+Tracks the visibility of an element within the viewport.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useElementVisibility } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const target = useTemplateRef('target')
+const targetIsVisible = useElementVisibility(target)
+</script>
+
+<template>
+  <div ref="target">
+    <h1>Hello world</h1>
+  </div>
+</template>
+```
+
+### rootMargin
+
+If you wish to trigger your callback sooner before the element is fully visible, you can use
+the `rootMargin` option (See [MDN IntersectionObserver/rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)).
+
+```ts
+import { useElementVisibility } from '@vueuse/core'
+// ---cut---
+const targetIsVisible = useElementVisibility(target, {
+  rootMargin: '0px 0px 100px 0px',
+})
+```
+
+### threshold
+
+If you want to control the percentage of the visibility required to update the value, you can use the `threshold` option (See [MDN IntersectionObserver/threshold](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#threshold)).
+
+```ts
+const targetIsVisible = useElementVisibility(target, {
+  threshold: 1.0, // 100% visible
+})
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseElementVisibility v-slot="{ isVisible }">
+    Is Visible: {{ isVisible }}
+  </UseElementVisibility>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script setup lang="ts">
+import { vElementVisibility } from '@vueuse/components'
+import { shallowRef, useTemplateRef } from 'vue'
+
+const target = useTemplateRef('target')
+const isVisible = shallowRef(false)
+
+function onElementVisibility(state) {
+  isVisible.value = state
+}
+</script>
+
+<template>
+  <div v-element-visibility="onElementVisibility">
+    {{ isVisible ? 'inside' : 'outside' }}
+  </div>
+
+  <!-- with options -->
+  <div ref="target">
+    <div v-element-visibility="[onElementVisibility, { scrollTarget: target }]">
+      {{ isVisible ? 'inside' : 'outside' }}
+    </div>
+  </div>
+</template>
+```
+
+## Type Declarations
+
+```ts
+export interface UseElementVisibilityOptions
+  extends ConfigurableWindow,
+    Pick<UseIntersectionObserverOptions, "threshold"> {
+  /**
+   * Initial value.
+   *
+   * @default false
+   */
+  initialValue?: boolean
+  /**
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin
+   */
+  rootMargin?: MaybeRefOrGetter<string>
+  /**
+   * The element that is used as the viewport for checking visibility of the target.
+   */
+  scrollTarget?: MaybeRefOrGetter<HTMLElement | undefined | null>
+  /**
+   * Stop tracking when element visibility changes for the first time
+   *
+   * @default false
+   */
+  once?: boolean
+}
+/**
+ * Tracks the visibility of an element within the viewport.
+ *
+ * @see https://vueuse.org/useElementVisibility
+ */
+export declare function useElementVisibility(
+  element: MaybeComputedElementRef,
+  options?: UseElementVisibilityOptions,
+): ShallowRef<boolean, boolean>
+export type UseElementVisibilityReturn = ReturnType<typeof useElementVisibility>
+```

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

@@ -0,0 +1,101 @@
+---
+category: Utilities
+---
+
+# useEventBus
+
+A basic event bus.
+
+## Usage
+
+```ts
+import { useEventBus } from '@vueuse/core'
+
+const bus = useEventBus<string>('news')
+
+function listener(event: string) {
+  console.log(`news: ${event}`)
+}
+
+// listen to an event
+const unsubscribe = bus.on(listener)
+
+// fire an event
+bus.emit('The Tokyo Olympics has begun')
+
+// unregister the listener
+unsubscribe()
+// or
+bus.off(listener)
+
+// clearing all listeners
+bus.reset()
+```
+
+Listeners registered inside of components `setup` will be unregistered automatically when the component gets unmounted.
+
+## TypeScript
+
+Using `EventBusKey` is the key to bind the event type to the key, similar to Vue's [`InjectionKey`](https://antfu.me/posts/typed-provide-and-inject-in-vue) util.
+
+```ts
+// fooKey.ts
+import type { EventBusKey } from '@vueuse/core'
+
+export const fooKey: EventBusKey<{ name: foo }> = Symbol('symbol-key')
+```
+
+```ts
+import { useEventBus } from '@vueuse/core'
+
+import { fooKey } from './fooKey'
+
+const bus = useEventBus(fooKey)
+
+bus.on((e) => {
+  // `e` will be `{ name: foo }`
+})
+```
+
+## Type Declarations
+
+```ts
+export type EventBusListener<T = unknown, P = any> = (
+  event: T,
+  payload?: P,
+) => void
+export type EventBusEvents<T, P = any> = Set<EventBusListener<T, P>>
+export interface EventBusKey<T> extends Symbol {}
+export type EventBusIdentifier<T = unknown> = EventBusKey<T> | string | number
+export interface UseEventBusReturn<T, P> {
+  /**
+   * Subscribe to an event. When calling emit, the listeners will execute.
+   * @param listener watch listener.
+   * @returns a stop function to remove the current callback.
+   */
+  on: (listener: EventBusListener<T, P>) => Fn
+  /**
+   * Similar to `on`, but only fires once
+   * @param listener watch listener.
+   * @returns a stop function to remove the current callback.
+   */
+  once: (listener: EventBusListener<T, P>) => Fn
+  /**
+   * Emit an event, the corresponding event listeners will execute.
+   * @param event data sent.
+   */
+  emit: (event?: T, payload?: P) => void
+  /**
+   * Remove the corresponding listener.
+   * @param listener watch listener.
+   */
+  off: (listener: EventBusListener<T>) => void
+  /**
+   * Clear all events
+   */
+  reset: () => void
+}
+export declare function useEventBus<T = unknown, P = any>(
+  key: EventBusIdentifier<T>,
+): UseEventBusReturn<T, P>
+```