feat(power): add usePower composable (#411)

docs/.vitepress/config.mts

@@ -94,6 +94,7 @@ function sidebar(): DefaultTheme.SidebarItem[] {
       items: [
         { text: 'Api', link: '/composables/api' },
         { text: 'Image', link: '/composables/image' },
+        { text: 'Power', link: '/composables/power' },
         { text: 'Url', link: '/composables/url' },
         { text: 'Utils', link: '/composables/utils' }
       ]

docs/composables/api.md

@@ -29,7 +29,7 @@ function useQuery<Data = any>(
 ```
 
 ```ts
-import { useQuery } from '@globalbrain/sefirot/lib/composables/Api.vue'
+import { useQuery } from '@globalbrain/sefirot/lib/composables/Api'
 
 const { data, loading } = useQuery((http) => {
   return http.get('/api/users')

docs/composables/power.md

@@ -0,0 +1,65 @@
+# Power <Badge text="3.10.0" />
+
+`Power` module provides a composable to work with modal state.
+
+## `usePower`
+
+```ts
+interface Power {
+  /**
+   * the modal state.
+   */
+  state: Ref<boolean>
+  /**
+   * shows the modal.
+   */
+  on(fn?: () => void): boolean
+  onAfter(fn: () => Promise<any>): Promise<boolean>
+  /**
+   * hides the modal.
+   */
+  off(fn?: () => void): boolean
+  offAfter(fn: () => Promise<any>): Promise<boolean>
+  /**
+   * toggles the modal state.
+   */
+  toggle(fn?: () => void): boolean
+  toggleAfter(fn: () => Promise<any>): Promise<boolean>
+}
+```
+
+```vue
+<script setup lang="ts">
+import SButton from '@globalbrain/sefirot/lib/components/Button.vue'
+import SModal from '@globalbrain/sefirot/lib/components/Modal.vue'
+import { usePower } from '@globalbrain/sefirot/lib/composables/Power'
+
+const { state, on, off } = usePower()
+</script>
+
+<template>
+  <SButton mode="info" label="Open dialog" @click="on" />
+  <SModal :open="state" @close="off">
+    <p>Modal content</p>
+  </SModal>
+</template>
+```
+
+You can also pass a function to `on`, `off` and `toggle` methods.
+
+```vue
+<script setup lang="ts">
+import SButton from '@globalbrain/sefirot/lib/components/Button.vue'
+import SModal from '@globalbrain/sefirot/lib/components/Modal.vue'
+import { usePower } from '@globalbrain/sefirot/lib/composables/Power'
+
+const { state, on, off } = usePower()
+</script>
+
+<template>
+  <SButton mode="info" label="Open dialog" @click="on(() => console.log('opened'))" />
+  <SModal :open="state" @close="off(() => console.log('closed'))">
+    <p>Modal content</p>
+  </SModal>
+</template>
+```

lib/composables/Power.ts

@@ -0,0 +1,58 @@
+import { type Ref, ref } from 'vue'
+
+export interface Power {
+  state: Ref<boolean>
+  on(fn?: () => void): boolean
+  onAfter(fn: () => Promise<any>): Promise<boolean>
+  off(fn?: () => void): boolean
+  offAfter(fn: () => Promise<any>): Promise<boolean>
+  toggle(fn?: () => void): boolean
+  toggleAfter(fn: () => Promise<any>): Promise<boolean>
+}
+
+export function usePower(initialValue = false): Power {
+  const state = ref(initialValue)
+
+  function on(fn: () => void = () => {}): boolean {
+    typeof fn === 'function' && fn()
+    state.value = true
+    return state.value
+  }
+
+  async function onAfter(fn: () => Promise<any>): Promise<boolean> {
+    await fn()
+    return on()
+  }
+
+  function off(fn: () => void = () => {}): boolean {
+    typeof fn === 'function' && fn()
+    state.value = false
+    return state.value
+  }
+
+  async function offAfter(fn: () => Promise<any>): Promise<boolean> {
+    await fn()
+    return off()
+  }
+
+  function toggle(fn: () => void = () => {}): boolean {
+    typeof fn === 'function' && fn()
+    state.value = !state.value
+    return state.value
+  }
+
+  async function toggleAfter(fn: () => Promise<any>): Promise<boolean> {
+    await fn()
+    return toggle()
+  }
+
+  return {
+    state,
+    on,
+    onAfter,
+    off,
+    offAfter,
+    toggle,
+    toggleAfter
+  }
+}