docs(use-disclosure): update types and JSDoc

Author: TylerAPfledderer

packages/vue-composables/src/use-disclosure.ts

@@ -1,19 +1,101 @@
-import { computed, HTMLAttributes, ref, watchEffect } from "vue"
+import {
+  computed,
+  ComputedRef,
+  HTMLAttributes,
+  Ref,
+  ref,
+  watchEffect,
+} from "vue"
 import { useId } from "./use-id"
 
 export interface UseDisclosureProps {
+  /**
+   * Defines open state from outside dynamic state being passed in.
+   *
+   * Overrides `defaultIsOpen` prop.
+   */
   isOpen?: boolean
+  /**
+   * Default state on render. Overriden by `isOpen` prop dynamically
+   * if outside state should pass in a truthy value
+   */
   defaultIsOpen?: boolean
+  /**
+   * Additional actions to run when the targeted element is closed.
+   */
   onClose?(): void
+  /**
+   * Additional actions to run when the targeted element is opened.
+   */
   onOpen?(): void
+  /**
+   * Custom id to connect the toggle with the targeted element for accessibility.
+   *
+   * @default `disclosure-<uid>`
+   */
   id?: string
 }
 
+type ReturnUseDisclosureType = {
+  /**
+   * Returns current state
+   *
+   * @default false
+   */
+  isOpen: Ref<boolean>
+  /**
+   * Actions run when opening targeted element.
+   *
+   * If target element is uncontrolled, then it includes toggle open.
+   */
+  open: () => void
+  /**
+   * Actions run when closing targeted element.
+   *
+   * If target element is uncontrolled, then it includes toggle closed.
+   */
+  close: () => void
+  /**
+   * Actions run when toggling open and closed.
+   */
+  toggle: () => void
+  /**
+   * Check if external functionality controls the state of the targeted element
+   */
+  isControlled: boolean
+  /**
+   * Computed object of Accessibility attributes and toggling event for the toggling element.
+   *
+   * `NOTE:` Pass this to the v-bind of the element.
+   *
+   * i.e. `v-bind='buttonProps'`
+   */
+  buttonProps: ComputedRef<{
+    "aria-expanded": HTMLAttributes["aria-expanded"]
+    "aria-controls": HTMLAttributes["aria-controls"]
+    onClick: HTMLAttributes["onClick"]
+  }>
+  /**
+   * Computed object of Accessibility attributes to show/hide targeted element and for aria controls.
+   *
+   * `NOTE:` Pass this to the v-bind of the element.
+   *
+   * i.e. `v-bind='disclosureProps'`
+   */
+  disclosureProps: ComputedRef<{
+    hidden: HTMLAttributes["hidden"]
+    id: HTMLAttributes["id"]
+  }>
+}
+
 /**
  * Handles common open, close, or toggle scenarios.
+ *
  * It can be used to control feedback components such as `Modal`, `AlertDialog`, `Drawer`, etc.
  */
-export function useDisclosure(props: UseDisclosureProps = {}) {
+export function useDisclosure(
+  props: UseDisclosureProps = {}
+): ReturnUseDisclosureType {
   const {
     isOpen: isOpenProp,
     onClose: handleClose,
@@ -24,7 +106,7 @@ export function useDisclosure(props: UseDisclosureProps = {}) {
 
   const isOpenState = ref(defaultIsOpen || false)
 
-  const isOpen = ref<boolean>(
+  const isOpen: ReturnUseDisclosureType["isOpen"] = ref(
     isOpenProp !== undefined ? isOpenProp : isOpenState.value
   )
 
@@ -49,35 +131,20 @@ export function useDisclosure(props: UseDisclosureProps = {}) {
 
   const toggle = () => (isOpen.value ? close() : open())
 
-  /**
-   * Computed object containing the HTML attributes for the button that
-   * is triggering the disclosure state
-   *
-   * `NOTE:` Pass this to the v-bind of the element.
-   *
-   * i.e. `v-bind='buttonProps'`
-   */
-
-  const buttonProps = computed(() => ({
+  const buttonProps: ReturnUseDisclosureType["buttonProps"] = computed(() => ({
     "aria-expanded": isOpen.value,
     "aria-controls": id.value,
     onClick() {
       toggle()
     },
   }))
 
-  /**
-   * Computed object containing the HTML attributes for the element that
-   * is being effected by the disclosure state.
-   *
-   * `NOTE:` Pass this to the v-bind of the element.
-   *
-   * i.e. `v-bind='disclosureProps'`
-   */
-  const disclosureProps = computed(() => ({
-    hidden: !isOpen.value,
-    id: id.value,
-  }))
+  const disclosureProps: ReturnUseDisclosureType["disclosureProps"] = computed(
+    () => ({
+      hidden: !isOpen.value,
+      id: id.value,
+    })
+  )
 
   watchEffect(() => {
     isOpen.value = isOpenState.value