composables.md

Vue Composables

This documentation covers the usage of four Vue composables: useDataTableOptions, useModal, usePrimeBindings, and useScroll.

Table of Contents

• useDataTableOptions - Datatable state management with Inertia
• useModal - Modal management system
• usePrimeBindings - PrimeVue prop merging and attribute bindings
• useScroll - Scroll utilities and detection

useDataTableOptions

The useDataTableOptions composable keeps datatable query options in sync with the backend via Inertia. It accepts a route configuration and initial options—typically the options array returned by the Atlas Laravel Inertia DataTable Options trait—and returns reactive refs for those options along with helpers to fetch new data.

Basic Usage

<script setup>
import { useDataTableOptions } from '@atlas/ui';
import { usePage } from '@inertiajs/vue3';

const { props } = usePage();
const table = useDataTableOptions('users.index', props.options);
</script>

API Reference

• search, perPage, sortField, sortOrder, filters, viewFields – reactive query option refs.
• selectAll, selected – selection helpers for rows.
• fetchData() – trigger an Inertia visit with the current options.
• resetSelection() – clear the current selection.

useModal

The useModal composable provides a flexible modal management system for Vue applications.

Basic Usage

import { useModal } from '@atlas/ui';

const modal = useModal();

// Open a modal
modal.open('confirmDialog', { message: 'Are you sure?' });

// Close a modal
modal.close('confirmDialog');

// Check if modal is open
const isActive = modal.activeState('confirmDialog');

// Get modal data
const modalData = modal.data('confirmDialog');

API Reference

Methods

• open(name: string, data?: unknown): Opens a modal with the specified name and optional data
• close(name: string): Closes a specific modal
• closeAll(): Closes all open modals
• activeState(name: string): Returns a reactive ref for the modal's open state
• data(name: string): Returns a computed ref of the modal's data
• isOpen: Computed property that returns true if any modal is open
• onOpen(name: string, callback: (data: unknown) => void): Register a callback when a modal opens
• onClose(name: string, callback: (data: unknown) => void): Register a callback when a modal closes

Examples

Using with v-model

<template>
    <Modal v-model="isActive">
        <!-- Modal content -->
    </Modal>
</template>

<script setup>
import { useModal } from '@atlas/ui';

const modal = useModal();
const isActive = modal.activeState('confirmDialog');
</script>

Using with Callbacks

<script setup>
import { useModal } from '@atlas/ui';

const modal = useModal();

// Register open callback
modal.onOpen('userForm', (data) => {
    console.log('User form opened with data:', data);
});

// Register close callback
modal.onClose('userForm', (data) => {
    console.log('User form closed with data:', data);
});
</script>

usePrimeBindings

The usePrimeBindings composable helps PrimeVue components merge props and attributes while applying PassThrough (PT) theming options.

Basic Usage

<template>
    <InputText v-bind="bindProps" :pt="mergedPt" />
</template>

<script setup>
import { usePrimeBindings } from '@atlas/ui';
import { useAttrs } from 'vue';

const props = defineProps({
    pt: Object,
    modelValue: String
});

const attrs = useAttrs();
const theme = { root: { class: 'p-2' } };

const { bindProps, mergedPt } = usePrimeBindings(props, attrs, theme, ['modelValue']);
</script>

API Reference

• bindProps – Computed object combining component attributes with props, excluding the pt prop and any keys provided in excludeKeys.
• mergedPt – Computed PT object produced by merging the provided theme with the component's pt prop using ptMerge.

useScroll

The useScroll composable provides utilities for scroll management and detection.

Basic Usage

<script setup>
import { useScroll } from '@atlas/ui';
import { ref } from 'vue';

const elementRef = ref(null);
const scroll = useScroll('myScrollContainer');

// Bind scroll handler to element
const scrollHandler = scroll.bindScrollHandler(elementRef);

// Add scroll listener
onMounted(() => {
    scrollHandler.add();
});

// Remove scroll listener
onUnmounted(() => {
    scrollHandler.remove();
});
</script>

API Reference

Methods

• isTop: Computed ref indicating if the scroll position is at the top
• setTop(value: boolean): Manually set the top state
• bindScrollHandler(elementRef: Ref<HTMLElement | null>): Binds scroll events to an element
• lockScroll(): Prevents scrolling on the document
• unlockScroll(): Restores scrolling on the document

Examples

Scroll Detection

<template>
    <div ref="containerRef" class="scroll-container">
        <div v-if="!isAtTop" class="scroll-indicator">
            Scrolled down
        </div>
        <!-- Content -->
    </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { useScroll } from '@atlas/ui';

const containerRef = ref(null);
const scroll = useScroll('container');
const isAtTop = scroll.isTop;

const scrollHandler = scroll.bindScrollHandler(containerRef);

onMounted(() => {
    scrollHandler.add();
});

onUnmounted(() => {
    scrollHandler.remove();
});
</script>

Modal with Scroll Lock

<script setup>
import { useModal, useScroll } from '@atlas/ui';

const modal = useModal();
const scroll = useScroll('modal');

// Lock scroll when modal opens
modal.onOpen('fullscreenModal', () => {
    scroll.lockScroll();
});

// Unlock scroll when modal closes
modal.onClose('fullscreenModal', () => {
    scroll.unlockScroll();
});
</script>

This documentation provides examples and usage patterns for both composables. For more specific use cases or advanced configurations, please refer to the source code or raise an issue in the repository.