wakeb-composables

wakeb-composables

Module, feature and theme loaders support optional-file fallbacks, typed diagnostics and bounded loading. Version 1.1.0 includes useFeatureComponent for nested optional features. See useFeatureComponent and resource registration for setup, fallback behavior and migration.

45+ reusable Vue 3 composables for Wakeb projects — TypeScript, RTL-aware, and i18n ready.

📖 Full Documentation →

Install

npm install wakeb-composables

Requirements

Quick Setup

For source changes and project-specific overrides, see Development and customization. The root entry statically imports integration peers, so direct consumers need them installed even when npm marks them optional. See Installation and the CommonJS compatibility notes.

Most composables work with a direct import—no plugin registration is required:

<script setup>
import { useTimer } from 'wakeb-composables'

const { formattedTime, resetTimer } = useTimer(60)
</script>

<template>
  <span>{{ formattedTime }}</span>
  <button @click="resetTimer">Restart</button>
</template>

The registry setup below is only required for dynamic module helpers such as useLookupPage, useModuleStore, and useModuleConfig, or for project-specific overrides.

Choose a detailed guide by use case:

• Simple formatting: useFormatFileSize
• UI interaction: useOnClickOutside
• File selection and chunked upload: useFileUpload
• Voice recording: useVoiceRecorder
• Registry-driven CRUD: useLookupPage

Registry setup

Create a plugin file and call registerWakebComposables() once before your router:

// src/plugins/wakeb-composables.js
import { registerWakebComposables } from 'wakeb-composables'
import { useBreadCrumbStore } from '@/stores/breadCrumb'
import { useEnumsStore } from '@/stores/enums'
import {
  handleErrors, resetSchemaValues,
  transformSchemaToObject, updateSchemaValues,
} from '@/utils/formDataHandler'

const storeModules  = import.meta.glob('/src/modules/*/stores/index.js')
const schemaModules = import.meta.glob('/src/modules/*/schema/index.js')
const configModules = import.meta.glob('/src/modules/*/config.js')

registerWakebComposables({
  storeModules,
  schemaModules,
  configModules,
  formHelpers: { handleErrors, resetSchemaValues, transformSchemaToObject, updateSchemaValues },
  async loadHelpers({ enums = [], models = [], configs = [] } = {}) {
    const store = useEnumsStore()
    await Promise.allSettled([
      enums.length   && store.getHelpEnums(enums),
      models.length  && store.getHelpModels(models),
      configs.length && store.getHelpConfigs(configs),
    ].filter(Boolean))
  },
  async applyBreadcrumbs({ folder, itemKey }) {
    const loader = configModules[`/src/modules/${folder}/config.js`]
    if (!loader) return
    const mod = await loader()
    const cfg = typeof mod.getDataEntryConfig === 'function'
      ? mod.getDataEntryConfig(itemKey) : mod.default
    if (Array.isArray(cfg?.breadcrumbs))
      useBreadCrumbStore().setBreadcrumbs(cfg.breadcrumbs)
  },
})

// src/main.js
import '@/plugins/wakeb-composables'  // before router

Registering Project Composables

Add your own composables to the registry — in bulk or one by one:

import { registerWakebComposables, registerComposable } from 'wakeb-composables'
import { useLogo } from '@/composables/useLogo'
import { useTheme } from '@/composables/useTheme'

// Option 1 — batch
registerWakebComposables({ composables: { useLogo, useTheme } })

// Option 2 — individual (safe to call anywhere, anytime)
registerComposable('useLogo', useLogo)

Retrieve them anywhere:

import { useComposable } from 'wakeb-composables'

const useLogo = useComposable('useLogo')
if (useLogo) {
  const { appLogo } = useLogo()
}

What's Included

App & UI

useAppSettings · useBreadcrumbs · useIsDark · useItemColor · useToast · useAlert · useResizableSidebar · useImageZoom · useOnClickOutside · useTeleport · useTextTruncator · useChildButtonRefs · useSound

Data & CRUD

useLookupPage · useModuleConfig · useModuleStore · useTableActions · useNestedLocation · useAxiosFetch · useModalFromQuery

Dates & Time

useDateRangePresets · useDateConverterToNow · useDateTimeFormat · useDateTimeFormatter · useHijriDate · useTimer

i18n & Locale

useArabicConverter · useAutoTranslate · useDirection · useKeyTypeCheck · useLanguageSwitcher · useLocaleDirection · useLocaleWatcher · useNumberConverter

Forms & Validation

useValidation · useVariableHandler · useFileUpload · useInitials

Storage & Security

storage · useCookies · useCryptoService

Media & Real-time

useVoiceRecorder · useMarkdown · useLaravelEcho · useFormatFileSize

Highlights

useLookupPage — Full CRUD in one call

const {
  STORE, schema, headers, actions,
  isShowModal, isCreate, modalTitle, addEditLoading,
  getItems, addRow, editRow, viewRow,
  submitForm, deleteRow, toggleActiveRow,
} = await useLookupPage({ itemKey: 'users' })

storage — LocalStorage wrapper

import { storage } from 'wakeb-composables'

storage.set('token', 'abc123')
storage.set({ mode: 'dark', locale: 'ar' })

const token = storage.get('token')
storage.remove('token')

useAlert — SweetAlert2 helpers

import { showAlert, confirmDelete } from 'wakeb-composables'

showAlert({ title: 'Saved!', type: 'success' })

const ok = await confirmDelete({
  title: 'حذف المستخدم؟',
  text: 'لا يمكن التراجع عن هذا الإجراء.',
  locale: 'ar',
  confirmText: 'حذف',
  cancelText: 'إلغاء',
})
if (ok) await deleteUser(id)

useToast — Lightweight toast

import { useToast } from 'wakeb-composables'

useToast({ message: 'Done!', color: 'success', location: 'top center' })

Tree Shaking

The package is fully tree-shakeable ("sideEffects": false). Only the composables you import are included in your bundle.

License

MIT © Kerolos Zakaria

AI Agent Skill

This package ships with an Agent Skill at docs/SKILL.md. The skill teaches supported AI coding agents the intended API, workflows, constraints, and verification steps for this package.

Install the package

npm install wakeb-composables

Install the skill for your AI agent

npx skills add ./node_modules/wakeb-composables/docs

The skills CLI can install the skill into supported agents such as Claude Code, Codex, Cursor, OpenCode, and many others. Run the command from your project root after installing the npm package.

To install globally instead of only for the current project:

npx skills add ./node_modules/wakeb-composables/docs -g

You can also target a specific supported agent with --agent, for example:

npx skills add ./node_modules/wakeb-composables/docs --agent codex

After installation, the agent can discover and follow the package skill automatically according to that agent's supported skill location.

Preferences and realtime state (1.1.0)

New public APIs: usePageViewPreference, usePersistentSettings, useNotificationSettings, useEchoSubscription, useRealtimeHighlight and useLookupState. These accept application state/adapters without importing Aware stores. See preferences, persistent settings, notifications, Echo subscriptions, highlights, and lookup state.