Composables Documentation

Overview

This section documents all Vue composables used in the Collage Brand Portal application. Composables are organized by functionality in app/composables/ and provide reusable, composable logic following Vue 3's Composition API patterns.

Composable Architecture

The composables are organized into a hierarchical structure that separates concerns:

composables/
├── api/                    # External API and TanStack Query (27 files)
│   ├── useAccountApi.ts
│   ├── useAppDataApi.ts
│   ├── useAppDataQueries.ts
│   ├── useAssetsApi.ts
│   ├── useAssetsQueries.ts
│   ├── useAuthApi.ts
│   ├── useCollectionApi.ts
│   ├── useCollectionQueries.ts
│   ├── useCommonApis.ts
│   ├── useDownloadApi.ts
│   ├── useExternalShareApi.ts
│   ├── useFetchClient.ts
│   ├── useFolderApi.ts
│   ├── useFolderQueries.ts
│   ├── useMutationClient.ts
│   ├── useNotificationApi.ts
│   ├── useProfileApi.ts
│   ├── useProfileQueries.ts
│   ├── useQueryClient.ts
│   ├── queryKeys.ts
│   ├── useSearchApi.ts
│   ├── useShareDialogApi.ts
│   ├── useSharingApi.ts
│   ├── useSharingQueries.ts
│   ├── useSupportApi.ts
│   └── useWorkspaceApi.ts
├── auth/                   # Authentication composables (4 files)
│   ├── customScheme.ts
│   ├── useAuth.ts
│   ├── useCookieHelper.ts
│   └── usePublicPortal.ts
└── core/                   # Core business logic composables
    ├── common/             # Common utilities (13 files)
    │   ├── useAccountStatus.ts
    │   ├── useAnalytics.ts
    │   ├── useBreadCrumbs.ts
    │   ├── useBrandingColors.ts
    │   ├── useCarouselSettings.ts
    │   ├── useCommonSearch.ts
    │   ├── useFileType.ts
    │   ├── useHelpers.ts
    │   ├── useImageStyle.ts
    │   ├── useRouteFromMiddleware.ts
    │   ├── useSearchUtils.ts
    │   ├── useToggleSelection.ts
    │   └── useViewModeCache.ts
    ├── components/         # Component-specific composables
    │   ├── card/           # Card component composables (4 files)
    │   │   ├── useAssetCard.ts
    │   │   ├── useAssetContainer.ts
    │   │   ├── useCollagecard.ts
    │   │   └── useFolderCard.ts
    │   ├── dialogs/        # Dialog composables (3 files)
    │   │   ├── useAssetConverter.ts
    │   │   ├── useQuickViewDialog.ts
    │   │   └── useShareDialog.ts
    │   ├── search/         # Search component composables (5 files)
    │   │   ├── useAddedFilter.ts
    │   │   ├── useListLevelThree.ts
    │   │   ├── useSearchAssets.ts
    │   │   ├── useSearchBar.ts
    │   │   └── useSearchFilter.ts
    │   ├── sharing/        # Sharing component composables (3 files)
    │   │   ├── useShareLinkListTable.ts
    │   │   ├── useShareTableHeader.ts
    │   │   └── useShareTableListItem.ts
    │   ├── useDamNotification.ts
    │   └── useHeader.ts
    ├── layouts/            # Layout composables (4 files)
    │   ├── useCollageSidebar.ts
    │   ├── useFavicon.ts
    │   ├── useSidebarCurrentFolder.ts
    │   └── useSidebarFolderTree.ts
    ├── miscellaneous/      # Miscellaneous utilities (5 files)
    │   ├── useCrypto.ts
    │   ├── usePdfJs.ts
    │   ├── usePdfJsViewer.ts
    │   ├── useSnackbar.ts
    │   └── useTxtViewer.ts
    └── pages/              # Page-specific composables (11 files)
        ├── useAssetDetails.ts
        ├── useCollage.ts
        ├── useCollageDetails.ts
        ├── useDashboard.ts
        ├── useExternalShare.ts
        ├── useFolderDetails.ts
        ├── useFolders.ts
        ├── useProfile.ts
        ├── useSearch.ts
        ├── useSharing.ts
        └── useSupport.ts

Total: 79 composable files

Architecture Principles

1. Separation of Concerns

• API Composables (api/): Handle external API communication only
• Auth Composables (auth/): Handle authentication and session management
• Core Composables (core/): Business logic and UI state management

2. Layered Architecture

┌─────────────────────────────────────┐
│         Pages/Components             │  ← UI Layer
├─────────────────────────────────────┤
│      Core Composables (core/)       │  ← Business Logic Layer
├─────────────────────────────────────┤
│      API Composables (api/)         │  ← API Communication Layer
├─────────────────────────────────────┤
│      Stores (Pinia)                 │  ← State Management Layer
└─────────────────────────────────────┘

3. Composable Categories

API Composables (api/)

• Purpose: External API communication
• Pattern: Return API methods (get, post, put, delete)
• Documentation: See Composable APIs Documentation
• Note: API composables are documented separately in the Composable APIs section

Auth Composables (auth/)

• Purpose: Authentication, session management, cookie handling
• Key Composables:
  • useAuth - Main authentication logic
  • useCookieHelper - HTTP-only cookie management
  • customScheme - Nuxt Auth module integration
  • usePublicPortal - Public portal access

Common Composables (core/common/)

• Purpose: Reusable utility functions used across the application
• Examples: Helpers, analytics, file type detection, breadcrumbs

Component Composables (core/components/)

• Purpose: Component-specific business logic
• Organization: Grouped by component type (card, dialogs, search, sharing)
• Pattern: One composable per component or component group

Layout Composables (core/layouts/)

• Purpose: Layout-specific logic (sidebar, folder tree, current folder state)
• Examples: useCollageSidebar - Sidebar state and navigation; useSidebarFolderTree - Tree expand/collapse and child loading; useSidebarCurrentFolder - Current folder for tree highlighting

Page Composables (core/pages/)

• Purpose: Page-specific business logic
• Pattern: One composable per page
• Responsibilities: Data fetching, state management, user interactions

Miscellaneous Composables (core/miscellaneous/)

• Purpose: Utility composables that don't fit other categories (notifications, crypto, PDF/text viewers)
• Examples: Snackbar notifications, crypto utilities, usePdfJs/usePdfJsViewer/useTxtViewer for asset preview

Composable Patterns

Basic Composable Structure

import { ref, computed } from 'vue'
import type { UseComposableReturn } from '~/types'

export function useMyComposable(): UseComposableReturn {
  // Reactive state
  const data = ref(null)
  const loading = ref(false)
  const error = ref(null)

  // Computed properties
  const isReady = computed(() => !loading.value && data.value !== null)

  // Methods
  const fetchData = async () => {
    loading.value = true
    try {
      const result = await api.getData()
      data.value = result
    } catch (e) {
      error.value = e
    } finally {
      loading.value = false
    }
  }

  // Return interface
  return {
    data,
    loading,
    error,
    isReady,
    fetchData
  }
}

Using Stores in Composables

export function useMyComposable() {
  const authStore = useAuthStore()
  const appDataStore = useAppDataStore()

  const fetchData = async () => {
    if (!authStore.isAuthenticated) return
    
    const workspaceId = getWorkspaceId()
    const data = await appDataStore.fetchDashboardData()
    return data
  }

  return { fetchData }
}

Component Composable Pattern

export function useMyComponent(props: Props, emit: Emits) {
  const { getWorkspaceId } = useHelpers()
  const snackbar = useSnackbar()

  const handleAction = async () => {
    try {
      await performAction()
      snackbar.showSuccess('Action completed')
      emit('success')
    } catch (error) {
      snackbar.showError(error)
      emit('error', error)
    }
  }

  return {
    handleAction
  }
}

Composable Categories

API Composables

Located in app/composables/api/, these composables handle external API communication. See Composable APIs Documentation for detailed information.

Note: API composables are documented separately. All 17 API composables are fully documented in the Composable APIs section.

Authentication Composables

Located in app/composables/auth/, these composables handle authentication and session management.

• useAuth - Main authentication composable with login/logout
• useCookieHelper - HTTP-only cookie management
• customScheme - Custom auth scheme for Nuxt Auth module
• usePublicPortal - Public portal access handling

Core Common Composables

Located in app/composables/core/common/, these are reusable utility composables.

• useHelpers - Workspace, brand, formatting helpers
• useAccountStatus - Account status checking
• useAnalytics - Analytics tracking
• useBreadCrumbs - Breadcrumb navigation logic
• useBrandingColors - Apply workspace branding to CSS variables
• useCarouselSettings - Carousel configuration
• useCommonSearch - Common search filter logic
• useFileType - File type detection and icons
• useImageStyle - Dynamic image styling
• useRouteFromMiddleware - Read route snapshot set by check-url middleware
• useSearchUtils - Shared search utilities (debounce, scroll, pagination, error messages)
• useToggleSelection - Selection management with shift-click
• useViewModeCache - View mode (grid/list) caching

Core Component Composables

Located in app/composables/core/components/, these composables provide component-specific business logic.

Card Composables

• useAssetCard - Asset card logic
• useAssetContainer - Asset container logic
• useCollagecard - Collage card logic
• useFolderCard - Folder card logic

Dialog Composables

• useShareDialog - Share dialog logic
• useQuickViewDialog - Quick view dialog logic
• useAssetConverter - Asset converter dialog logic

Search Composables

• useSearchBar - Search bar logic
• useSearchFilter - Search filter panel logic
• useSearchAssets - Search results logic
• useAddedFilter - Added filter option logic
• useListLevelThree - Level 3 filter menu logic

Sharing Composables

• useShareLinkListTable - Share link table logic
• useShareTableHeader - Share table header logic
• useShareTableListItem - Share table item logic

Global Component Composables

• useHeader - Header component logic
• useDamNotification - DAM notification logic

Core Layout Composables

Located in app/composables/core/layouts/, these composables handle layout-specific logic.

• useCollageSidebar - Sidebar state, navigation, and brand data
• useFavicon - Watches brand favicon URL and syncs <link rel="icon"> in DOM (client-only)
• useSidebarFolderTree - Sidebar folder tree state, expand/collapse, lazy-loaded children
• useSidebarCurrentFolder - Current folder state for tree highlighting

Core Miscellaneous Composables

Located in app/composables/core/miscellaneous/, these are utility composables.

• useSnackbar - Snackbar notification utility
• useCrypto - Encryption/decryption for search state
• usePdfJs - Shared PDF.js library instance
• usePdfJsViewer - PDF viewer logic (zoom, thumbnails, find-in-page, proxy)
• useTxtViewer - Plain-text viewer logic (zoom, fit, find-in-page, proxy)

Core Page Composables

Located in app/composables/core/pages/, these composables provide page-specific business logic.

• useDashboard - Dashboard page logic
• useFolders - Folder list page logic
• useFolderDetails - Folder details page logic
• useCollage - Collage list page logic
• useCollageDetails - Collage details page logic
• useSearch - Search page logic
• useSharing - Sharing page logic
• useAssetDetails - Asset details page logic
• useProfile - Profile page logic
• useExternalShare - External share page logic
• useSupport - Support/feedback page logic

Best Practices

1. Single Responsibility: Each composable should have a single, clear purpose
2. Type Safety: Always define return types using interfaces from ~/types
3. Error Handling: Implement consistent error handling with try/catch
4. Loading States: Provide loading state management for async operations
5. Reusability: Make composables reusable across components and pages
6. Documentation: Document parameters, return values, and usage examples
7. Naming: Use descriptive names starting with use (e.g., useDashboard)
8. State Management: Use stores for global state, composables for local/component state
9. API Calls: Centralize API calls in API composables (api/ folder)
10. Dependencies: Minimize dependencies between composables
11. SSR Compatibility: Ensure composables work with SSR (use import.meta.client checks)
12. Reactive State: Use ref and computed appropriately for reactive state

Related Documentation

• Composable APIs - External API composables (17 files)
• Components - Components that use these composables
• Pages - Pages that use page composables
• Stores - Pinia stores used by composables
• Types - TypeScript types for composables